Building An API – Lessons Learned

In 2011 my boss came to me and asked me to design an API for our product. I had been exposed to APIs in the past in my role as a developer, but I had never thought about designs, architecture or best practices.

After doing a bit of research, I presented my team with a macro design about how the API would work.  It was going to follow this great standard for APIs called ‘REST’.

The following links were invaluable during the concept and design phases of the API:

The Firefox Rest Client plugin (a MUST for any API work).  The Chrome ‘Advanced Rest Client’ is also extremely useful.

Best Practices for designing REST APIs
A really excellent article around the reasons why REST APIs should be designed the way they are. Brilliant stuff.

RESTful API Design: Teach a Dog to REST
A great presentation on the best practices and principles of restful architecture and design.

REST API Tutorial
A step-by-step tutorial on what REST is and why it is good

REST Anti-patterns
A good article about the do not’s of REST

How I explained REST to my Wife
A condescending look at how to explain REST to a non-technical person.  I thought this was a really good article about why REST should be used correctly for machine-to-machine APIs.

The API that I designed has now been in production for about 3 years and I’m writing this post because if I was doing this all over again, there’s a few things that I would have liked to know; namely:

  1. REST – Best Practice vs Practicality
  2. Practicalities of versioning your API
  3. How do users want to see you securing your API
  4. API Service Providers (Mashery vs Apigee)
  5. API Deployment and Updates
  6. Developer Community & Examples
  7. Carding for Developers (Agile Story Cards)
  8. Documentation (i/o docs & swagger)
  9. Gaining user feedback on the API

Over the next few weeks I’ll be populating this blog with content around these areas and others.

Please feel free to drop me a line if you’re curious about any other aspects of the API design and current implementation.