I like machine readable definitions that are also human readable. Depending on how much you care about your API consumers, and how mature your API life cycle is, your will invest different amounts of energy into crafting your API definitions. Many will just autogenerate them, putting little refinement into them, relying on services and tooling to do most of the work. However, those who understand the value of API documentation will realize that investing in the details of your API definition and design will realize a bigger return when it comes to on-boarding developers with their API.
API definitions, whether OpenAPI, Postman Collection, or other format should be accessible and always strike a balance between being both machine and human readable. API definitions are primarily used for API documentation, and secondarily used for API mocking, testing, monitoring, security, code generation, and other stops along the API life cycle. While all of these stops along the API life cycle help contribute to the maturity and robustness of your API definitions, heavy investment in API documentation will ave the greatest ROI when it comes to making an impact on our human stakeholders. Helping attract users to your APIs, on-boarding them with less friction, and help increase their adoption and integration of resources into their applications.
Take the time to add summaries and descriptions to each path in your API definitions. Make sure that every request body and response has an example. Ensure that you take the time to be concise, but informative when crafting the API definitions—your API documentation will be better off for it. Make sure you aren’t hand-rolling your API documentation and are taking advantage of the wealth of OpenAPI and Postman collection driven documentation solutions. These types of API documentation just look better, and help reduce friction when on-boarding new developers, and giving existing API developers what they need when they come back to learn about new APIs, and expand their usage of existing APIs.
It can be easy to focus on the use of API definitions for the automation of the API life cycle, over thinking of them for humans. However, it is the human readability and added touches that are meant for human consumption that will make your APIs better. The human readability of your API definitions will help strengthen the feedback loop with API stakeholders involved in the delivery, usage, and evolution of your APIs. Pushing the human readability of your API definitions will help keep your API definitions speaking to not just developers for integration into other systems, and driving different stops along the API lifecycle—it will keep your API definitions acting as business contracts meeting the needs of your organization, making sure APIs don’t just work, but they are also properly solving actual problems that need addressing across business operations.