I am sure you can recognize a well designed API when you see it. But how to build one?
The truth is that no one can possibly know how to build a successful API — without first knowing the API consumers and their preferences. So when people ask me how to design a successful API, I usually ask back
“What do you need to do, so your consumers think that your API is simple, clean, clear and approachable?”
When I pose the question like that, some people shoot back: “REST!”, “Hypermedia!” or “HATEOAS!”
Hold on — don’t pull the trigger so quickly. Let’s think about that for one more moment.
Granted, it is true that it is much easier to design an API that is simple, clean, clear and approachable, when using REST. The design constraints that you subscribe to when using REST, direct you towards a simpler, cleaner, clearer, and more approachable interface design. I personally love RESTful architectures for that reason.
But just because it is easier for us designers to build a simple, clean, clear and approachable API with REST, does not mean that REST is the only right way to build APIs. Let’s not forget that “simple, clean, clear and approachable” is a subjective measure. For some groups of API consumers, a SOAP service might actually be much better … that is … as long as the resulting SOAP API is — well — simple, clean, clear and approachable.
Build consumer-oriented APIs. API consumer preferences matter – take them serious. Build simple, clean, clear and approachable APIs – from the perspective of your consumers. An API can be simple from the perspective of the API provider because it is similar to the services they already have. This is not what we understand by simple. It is the consumer’s perspective that matters, get to know their idea of a clean, clear and approachable API. Just ask them. The answers will guide you towards a consumer-oriented API, which is much more likely to become successful.
Don’t get too obsessed about the style. It does not matter so much which protocols are used to reach these characteristics, whether with REST, SOAP or RPC … the important thing is THAT they are achieved from he perspective of your consumers. If in doubt, remember that it becomes much easier to build good APIs, when subscribing to the REST constraints.
Read more on foundations and best practices for designing APIs that your consumers will love.
