Building an API - Lessons Learned

by Jordan Walsh

In 2011 my boss came to me and asked me to design an API for our product.

My response. API? Sure! What’s that?

Although I had been exposed to APIs in the past in my role as a developer, I had never thought about the API design from a supplier perspective, only ever a user. I now had to think about this from a whole new angle.

Where to start…?

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 amazing standard for APIs called ‘REST’.

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

Postman
A powerful GUI platform to make your API development faster & easier, from building API requests through testing, documentation and sharing.

Runscope
Proxy the requests from your app to your API with Runscope. Verify that your APIs are returning the correct data. This tool deserves an entire blog post on it’s own. Just sign up and use it.

Best Practices for designing REST APIs
An excellent article around the reasons why REST APIs are 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. A must for anyone getting introduced REST APIs.

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

The API that I designed has now been in production for over 6 years and I’m writing (re-publishing) this post because if I was doing this all over again, there’s a few things that I would have liked to have known, namely:

  1. REST — Best Practice vs Practicality
  2. Versioning your APIs
  3. Securing your APIs
  4. API Service / Gateway Providers
  5. API Deployment and Update methodologies
  6. Developer Community & Examples
  7. Carding for Developers (Agile Story Cards)
  8. Documentation (OpenAPI Spec)
  9. User feedback!

Over the next few months I’m going to be pushing content related to each of these areas, so stay tuned!

Please feel free to drop me a line if you’re curious about any other aspects of the API design and any decisions that I made along the way.

Originally published at jordwalsh.com on April 26, 2014.