Building APIs is hard.  Period.  Building RESTful APIs is a bit different, and requires in some cases more thought than generic internal APIs.  All it takes is mentioning PayPal and Stripe together in the same conversation to realize that building RESTful APIs is not child’s play.  When it’s executed well, it becomes an evangelistic tool, a delight for developers everywhere.  When executed poorly, well, just ask PayPal.

I bring all of this up because we’re in the process of building out a RESTful API for WP e-Commerce.  When I say “we”, I really mean that my friend, Pippin, is doing 99% of the work and I’m coming in and taking most of the credit.  #BOOM

But in all seriousness, he’s built a fantastic REST API for EDD and he’s being incredibly generous in porting a lot of it over to WPeC.  My hope is that by working together, both plugins end up with better APIs all around.  Collaboration is always greater than competition, and he understands that better than almost anyone I know.

Back to REST APIs though.  This post is really just me, thinking out loud, researching slowly.  I know some things that I don’t like, and I know some things that I do like.  I don’t like when endpoints include version numbers (use HTTP headers for this), verbs or query strings.  I do like when you only have to authenticate for private data; not all endpoints should require authentication.  I prefer HTTP response codes over random error codes, or at least in conjunction, when possible.  I hate SOAP and XML.  I love JSON.  Everything else is irrelevant (seriously).

Enough jibba-jabba.  Here’s some resources I’m mulling over as I prepare to work on our REST API.  I’d love to hear from you in the comments if you have experience building REST APIs or have found other helpful resources:

• Intro to REST (Great primer, technical overview of what constitutes a strictly RESTful API)
• High Performance APIs (A presentation from some of the guys behind LinkedIn’s API)
• Creating an efficient REST API (A very practical look at creating an API based on the basic principles of REST.  Note: I don’t agree with everything in this.)
• RESTful API Design, 2nd ed.
• RESTful Best Practices ( A presentation on building REST APIs in Ruby on Rails.  Ruby has some slick stuff for REST API implementation.  It kind of blows PHP away in that regard.  Regardless, it’s helpful for patterns and concepts. )
• RESTful Web Services (It’s a book.  Buy it if you build this stuff.)
• What Makes a Great Open API? (Great presentation, less technical, more high-level, business logic, concepts.  The whys, not the hows or whats.)