I have experience building APIs and strong opinions on what makes a great one. A well-designed API is important because, in a way, it serves as a form of marketing to other organizations, showcasing your technical competence. That’s why it’s worth investing the time to build high-quality APIs.
"A well-designed API is an invitation for developers to integrate with your platform."
An API starts with a good user interface, and for an API, that UI is its endpoints and documentation. Endpoints should clearly communicate where to interact with resources. If an organization uses internal nomenclature that differs from common industry terms, it’s often better to adopt the more widely recognized names to improve usability. Additionally, if a single endpoint can return a wide variety of resources based on query parameters, consider breaking it into multiple focused endpoints for better clarity and usability.
"API documentation should be treated as a marketing asset, not just a technical reference."
API documentation should be treated as a marketing asset, not just a technical reference. Its purpose extends beyond listing available endpoints—it should also serve as a persuasive guide for developers, enticing them to integrate with the API. Providing code examples in multiple languages, rather than just a cURL command, can make integration easier. Documentation should also anticipate the most common use cases, offering examples that go beyond basic request/response structures.
Spotify does an excellent job with its API documentation by embedding an interactive REPL alongside the API descriptions. Developers can enter their client keys and make live API calls in the context of their own accounts. This hands-on approach enhances the learning experience and accelerates adoption.
API versioning strategy needs to be carefully planned because changing course later is both costly and difficult. Versioning can be handled through the URI path, query parameters, headers, or even separate domains. However, an equally important consideration is how future versions will be supported alongside deprecated ones. This is a topic likely to spark debate among team members, as there is no universally perfect solution.
"Error messages can be the difference between a good API and a great one."
Error messages are often overlooked, yet they can be the difference between a good API and a great one. A single API call can fail for multiple reasons, and great APIs provide distinct HTTP status codes and clear, detailed error messages. For example, if a user tries to create an account without entering an email address, returning 422 Unprocessable Entity: “Email is required” is appropriate. If the email is already taken, an API could return either 422 Unprocessable Entity: “Email taken” or 409 Conflict: “Email is taken”. The latter is slightly preferable because 409 Conflict more accurately conveys the nature of the error. Specific error handling allows client developers to provide more precise feedback and improve the overall user experience.