What to avoid when designing Restful APIs
After another painful integration of one of those new fancy Swagger/OpenAPI-„based“ interfaces, this one goes out to everyone designing REST interfaces.
- If you are developing a RESTful API, you should expose resources that can be modified via http verbs (methods). Do not expose a list of key-value pairs at the interface to get a generic interface that seems to never change over time. This is especially true if you are using Swagger or OpenAPI Specifications. You don't get kudos from the consumers for the most generic interface of all time. You get kudos for comprehensibility, testability or the ability to generate code.
- If you do use a list of key-value pairs, then at least do not use IDs (or UUIDs) for keys or resource names. Anyone can imagine what could be meant by customer resource, but this is not the case for a resource with the name 550e8400-e29b-11d4-a716-446655440000.
- The use of the OpenAPI Specification (OAS) is a really good idea to describe the structure and behavior of your RESTful API. It helps to understand to your API!
- Do not hide the specification in your application, publish it. The specification is a contract, and all parties should know it.
- If you are building a UI based on the API, use the same language in the UI as in the resource definitions of your API. Especially, if there is no documentation of the API. No two names for the same thing!
- Do not miraculously modify the attributes after you have sent a 200 OK. This applies in particular to IDs that are subsequently added to attributes to ensure uniqueness. IDs such as primary keys should be generated by the server and then sent to the client in the response body. By the way, if you generate an ID on the server, make sure that the same ID is not used in a parallel session as well.
... to be continued!