For example, which endpoints are users hitting the most? In most cases, data reveals some really interesting patterns that you can leverage for your next API version. Also, if you have SDKs too, make sure they use user-agents. Your API logs will then log these user-agents for you to analyze later.
Is the endpoint naming consistent with whatever your business already has?
If you are starting from scratch, always use a plural noun. Use sub-resources to denote relations and information/entity hierarchy.
Did you define the HTTP verbs and the status codes that the endpoint supports?
Sometimes, a 404 is better to be sent than a 403 to avoid accidental leakage of information to unauthorized users. So, it is usually best to send a 404 for user-level resources or sub-resources and a 403 for base resources.
Did you define the success responses and error responses?
Almost every API has the response data in JSON, but you might want to support XML as well if you have enterprise customers, or your use case requires the data to be in XML. Did you also prepare a list of error codes that will be thrown by this endpoint - and how the users should resolve these errors?
Is the API scope too huge?
You might then want to split the spec into multiple logical items. Remember that you can always add scope easily to the API later, but cannot remove functionality once it is public with the same level of ease.
Do you expect this API endpoint to return a huge list?
In that case, you might want to define the pagination strategy (identifier-based offset like
after=xyz&limit=10 or index-based offset like
offset=10&limit=10), filters to be supported and the aliased endpoints for most-used filters.
Do you expect your users to use the API from a browser?
You might want to check on enabling CORS and having a token-based authentication.
Does your API endpoint return a timestamp?
If yes, define the format in which the timestamp will be returned (usually ISO 8601).
Do you expect the API calls to be authenticated?
If yes OAuth 2 is most preferred for most client-side authentication, Basic Auth is widely used for server-side authentication. Sometimes JWT can be used for client-side auth.
Do you expect your users to use the API from behind a GET-POST proxy?
Some enterprise proxies won’t allow HTTP verbs other than
POST. In that case, it is best if the API can allow an
X-HTTP-Method-Override header in the request while sending a
Do you need your API endpoint rate-limited?
It is a good idea to rate-limit your users as per your fair usage policy or acceptable usage policy. Github API is a very good example of this:
X-RateLimit-Limit header to specify the maximum number of requests users can make in a given period,
X-RateLimit-Remaining to specify the number of requests remaining in the current window and
X-RateLimit-Reset to specify the time at which the current window is reset (UTC epoch seconds)
Is the API endpoint versioned?
It is normal for the APIs to evolve as the customers and their products do. So it is better to have versioned APIs so that the APIs can be changed to the next version without breaking the existing API and thus without breaking the production code of your customers.
Do I need to provide the users with an SDK?
The answer is mostly yes if you are building for the general audience. If it is an internal API, an SDK might be overkilling it - you can delay building these SDKs if these aren’t public-facing. If you need the SDKs to be developed, then you will have to define the interfaces that are consistent across resources. Decide on the languages to be supported and prioritize them after talking to the consumers. Have a look at my spec checklist for SDKs at this stage to finalize your spec.
It is a good idea (might not be scalable though) to mock the APIs (I use Flask for this - I just need to define the routes and return a static JSON) to build a prototype of what the users would build on their end. Doing this will help us identify what is missing in the APIs that aren’t helping the users achieve their goals.
That’s a wrap! This is what worked for me so far while designing usable APIs and I hope it works for you too.