What makes a good REST API?
Today, anyone with basic programming skills can build an API. Frameworks like FastAPI, which provide an intuitive interface and are well documented, make it really easy. But what does it take to ship and maintain a robust REST API that other developers love using, that always works as expected and scales well?
I won’t go into too much detail in each section, but instead I’ll link to further resources on the topic for those that are interested to go deeper.
A good API has a well thought out and logical design of endpoints, returns data in a manner that is easy to consume, and provides detailed feedback in case of errors.
A good API has a complete OpenAPI specification that acts as a contract between the API provider and consumers. It is also used to create comprehensive documentation and SDKs.
Many web frameworks offer support for auto-generating an OpenAPI specification from endpoint definitions in the API’s codebase, either out of the box or via third-party libraries. You can use annotations to add additional details such as descriptions and examples. Keeping a single source of truth through a tight integration with the web framework helps keep the specification up-to-date and version-controlled alongside the codebase.
