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.)
Category:
Education, General

Join the conversation! 4 Comments

  1. I love me some RESTful APIs! I have helped several companies design them. So much fun!

    Reply
  2. I can unequivocally say that building the WPEC REST API has dramatically improved the one Dan Griffiths (he built the entire v1.0 of our API) and I built for Easy Digital Downloads.

    APIs take a ton of work and they usually are not that good with 1.0. The one we built for EDD was okay at first; it laid the framework, but as we improved it, it became pretty darn awesome, and now that I get to step back from it and see how well it integrates into another system, I get to see all of the pitfalls 1.0 had and improve upon them.

    Reply
  3. […] them. There are some great tools for making REST requests (Paw, Insomnia, Postman) for testing APIs you are building, as well as tools for generating test/sample REST responses (Mocky) for testing API […]

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *