Now completely between us: You're following the trend, opening up your system “to the outside world” with a RESTful HTTP interface, and the whole thing in an agile approach — and then that! Consumers are complaining. You've even documented your interface and will promptly adapt it to new requirements and feedback! So WHY does anyone hate your API?
Perhaps consumers simply have no idea. But maybe our not too serious hate catalog will also help you. To do this, we will take the first-person perspective of your (rather grumpy) API consumer below.
I'm your consumer — and I hate your API because...
... my application unexpectedly aborts every few weeks because your API suddenly reacts differently
It's nice that you're adding “improvements” and new features with every sprint. However, I am surprised when more information (e.g. new attributes) is suddenly provided in the response. And yes, it's great that you've even adjusted your API description accordingly. But I didn't actually set up any monitoring on it. And if you then send back new or different error codes or incorporate pagination, then these are really “breaking changes” for me!
So a suggestion for goodness: It's totally okay for me if I enter a version number in my request (e.g. in the URL) — and have to actively switch over from time to time because you are switching off an old version. But please — version your API and keep old versions alive in parallel for at least a while. Then I can rebuild and test in peace and then even enjoy new features. Oh so: And maybe you could even actively notify me about new versions and sundowns, e.g. on the portal where you published your API, in the API response or, more traditionally, via newsletter (see also How to Smartly Sunset and Deprecate APIs)?
... your API always responds with HTTP Response Code 200
HTTP response codes are not high science [Author's note: sometimes in detail 😉]. I'll make it very simple and limit myself to at least three main groups and a few examples from each group:
Okay, I'm not infallible either. It would be nice if you could help me recognize my mistake. It is welcome to be a bit more detailed than just HTTP Status Code 400.
I know that's unpleasant, but if you're aware of the problem, a few details would be nice — and I don't mean your internal stack trace!
... my requests take forever to get an answer
If you really can't process the request as quickly (after taking advantage of other performance improvements through caching, etc.), then asynchronous processing may be better — possibly with HTTP Response 202 (ACCEPTED). Give me back a reference and I can periodically ask about the status if necessary.
... I have already caused your API to crash several times due to heavy load
If you tell me your SLAs (Service Level Agreements), I can at least take that into account on my side as well.
However, protective mechanisms such as circuit breakers, spike arrests and quotas should also ensure this on your part.
... I need to write to you first to tell you that your API isn't working right now
Such provider-side monitoring is a great thing — but I understand that consumer-driven alerting is the easier option. But only for you as a provider and definitely not for me.
... your API is incompletely documented and I therefore have to play HTTP-Response-400-Ping-Pong
I don't recognize any distinction between optional and mandatory fields, attributes with only two possible values are only as strings (instead of enumeration — see also OpenAPI Spec: Enums) and all error cases are completely missing from your documentation. To get this information at least for request objects, I'll send all possible request combinations against your API and see when I get HTTP Response 400. Instead, something like this would be nice:
paths:
/persons:
Get:
Parameters:
- in: query
Nom: Surname
required: true
Description: Surename of the person you are searching for
scheme:
Type: string
- in: query
Name: sort
Description: Alphabetical Order of Persons by Surname
scheme:
Type: string
enum: [asc, desc]
In addition, there is no description of your SLAs (are there quota restrictions, for example) and security is also not defined (yes, even if it is just an API key). The fact that endpoints are missing for all environments (for production and — preferably — test or tryout) is then the smallest problem.
... I can't test your API
I'm building a great application and integrating your API. Compiled, done. For testing purposes, I generate from your API documentation (OpenAPI and Swagger Tools Thank you) even a mock server that I'm testing against. So far, so good. But somehow I'd like to do a few more real integration tests. But unfortunately, you don't have a test or tryout endpoint that I can access. Maybe you even have it, but I can't test because I'm not a resource owner myself. This means that I do not own any data and due to the authorization I am not allowed to access any data — for example, I cannot read out vehicle data because I don't have a test vehicle with you myself.
That's why...
Imagine you're a consumer and want a good API. And then try to implement these wishes as a provider as well. Perhaps the following guidelines will help you with this:
- Create a consumer-friendly API design — don't forget the errors!
- Versioning your API
- Implement a robust and stable application
- Monitor your API yourself and proactively respond to issues
- Document as if you don't know your API
- Enable testing
- Inform your consumers about changes and problems
Maybe your API consumers won't love you anyway — but hopefully your API 😉 And if you're a consumer and nodded heavily on every line: Imagine that YOU were the API provider.
