The key to a great API? Have the developer / designer of the API write the first set of client applications before the API is published externally. I have integrated with many dozens of APIs over the years and it is immediately obvious (and unfortunately too common) when the designer of the API has never been in the seat of the client developer.
Sorry for not pointing to specific examples, but things I really love to see in an API:
- Fully qualified URLs in all links (makes navigating and discovery in Postman a breeze).
- Ability to expand resources represented by links (even deeply nested resources) so I can get exactly what I need in a single request.
- The ability to specify what parts of the response resource to include / exclude, allowing me to slim the response to exactly what I need. More important in clients running on mobile devices where slender responses make a noticeable performance difference.
- The exact same URLs (including hostnames) for the test and production API, the difference between the environments being determined by the credentials used in the request. This greatly simplifies code in the client test and production environments.
- Security schemes that allow me to write serverless client applications (OAuth 2 implicit grant). This certainly requires more work by the API developer, but makes it possible to crank out all sorts of useful tools quickly, and massively reduces client IT overhead. This may not be appropriate for all APIs, but could be used a lot more often than it is.
- Along with the above, support for CORS so we don't have to mess around with JSONP and other hacks in the browser.
- If you make me eat your timezone, please please make it UTC. But spend a little extra effort and allow me to pass a timezone in, either as an account settings and/or request parameter (and a simple offset isn't good enough - support actual timezones so daylight saving is handled). It can be incredibly hard to analyze data in responses when you're constantly having to translate the time to your own to give proper context. Timezone support isn't fun but libraries make it pretty easy. This is more important in APIs that provide lots of transactional data.
- Let me attach meta data to resources - it doesn't even have to be a lot. Sometimes allowing me to slip in a handful of bytes removes the need for an entire database on my side.
- Be painfully explicit in error responses. State the obvious, especially in errors that are likely to occur at the beginning of integration such as issues with authentication, content types, payload structure, etc.
> - Let me attach meta data to resources - it doesn't even have to be a lot. Sometimes allowing me to slip in a handful of bytes removes the need for an entire database on my side.
So much +1's for this. Even better if I can query for it.
Yeah. And at very least budget some API dev time to respond as the client design unfolds. A static API, with an frontend app in discovery phase is a sad state of affairs.
Sorry for not pointing to specific examples, but things I really love to see in an API:
- Fully qualified URLs in all links (makes navigating and discovery in Postman a breeze).
- Ability to expand resources represented by links (even deeply nested resources) so I can get exactly what I need in a single request.
- The ability to specify what parts of the response resource to include / exclude, allowing me to slim the response to exactly what I need. More important in clients running on mobile devices where slender responses make a noticeable performance difference.
- The exact same URLs (including hostnames) for the test and production API, the difference between the environments being determined by the credentials used in the request. This greatly simplifies code in the client test and production environments.
- Security schemes that allow me to write serverless client applications (OAuth 2 implicit grant). This certainly requires more work by the API developer, but makes it possible to crank out all sorts of useful tools quickly, and massively reduces client IT overhead. This may not be appropriate for all APIs, but could be used a lot more often than it is.
- Along with the above, support for CORS so we don't have to mess around with JSONP and other hacks in the browser.
- If you make me eat your timezone, please please make it UTC. But spend a little extra effort and allow me to pass a timezone in, either as an account settings and/or request parameter (and a simple offset isn't good enough - support actual timezones so daylight saving is handled). It can be incredibly hard to analyze data in responses when you're constantly having to translate the time to your own to give proper context. Timezone support isn't fun but libraries make it pretty easy. This is more important in APIs that provide lots of transactional data.
- Let me attach meta data to resources - it doesn't even have to be a lot. Sometimes allowing me to slip in a handful of bytes removes the need for an entire database on my side.
- Be painfully explicit in error responses. State the obvious, especially in errors that are likely to occur at the beginning of integration such as issues with authentication, content types, payload structure, etc.