Tips for good API design

Design
1

Does anyone have any tips and possibly reading (or viewing) material that discusses good API design? I know everyone kind of does things differently, but I’m very interested to see what the industry as a whole is doing in the space of API design and implementation as I start building more API’s that end up getting larger or more sophisticated.

1 Like
2

I think the best option is the Rails 5 API feature. It’s optimized for best API Performance. If you look at a slightly better performance, Django is better(bcoz of the python scalability).

3

I’ll keep those in mind thanks. However, more specifically, what about actually designing endpoints and how a user will interact with the API to get and manipulate resources.

On a basic level I get the difference between methods and something like items gets all items but items/:item_id gets one item. But lets say the user wants to have those sorted or limited, how are people writing API’s these days to account for those types of scenarios.

4

If you build your API according to how Ember expects it, using either the REST serializer or JSON API serializer, then I’d say that is a pretty standard way of doing it, especially when it comes to Ember.

JSON API takes the protocol (verb, url, etc) and response format into consideration so you might want to take a look at the spec at http://jsonapi.org/.

I’ve started reading this book too on building APIs and its good: http://smile.amazon.com/Build-APIs-You-Wont-Hate/dp/0692232699/ref=sr_1_1?ie=UTF8&qid=1452289630&sr=8-1&keywords=api+phil

For your more specific question on sorting and limiting, you often see those params taken care of in the query string for endpoints.

1 Like
5

Joshua Bloch had an amazing presentation about software API design in 2005. These rules are relevant and adoptable to endpoint API design as well. I think, those principals can help to architect a more solid and maintainable structures.

Slides: http://lcsd05.cs.tamu.edu/slides/keynote.pdf

Video: How to Design a Good API & Why it Matters

6

I’m going to list a few guidelines of my own:

  • The best API is the one you would like to consume. Use ember-cli-mirage to test that your API, improve it and once you like it, create the real one.
  • If you can use the JSON:API spec, do it. It’s very flexible, and you most of the important decisions are already taken so you focus in what matters.
  • Status codes are important. 302, 401, 403, 422, 404. All of them mean something.
  • This one is important, an many people disagrees: Never, ever sideload at first. Create and endpoint for each kind of resource, even if that means you need one extra request. Sideloading can be useful to improve the performance by saving requests, but chances are your initial guess will be wrong. Start without sideloading, measure, and take a decissions of what you should sideload based on data, not intuition. And sideloading should be something the client explicitly asks for, never implicit.
  • Make your endpoints capable to returning more than one record. I mean things like /users?ids=[1,3,5] and enable coalesceFindRequests in your adapters. You will see that your need of sideloading is generally smaller than you thought.
1 Like