October 2015 Summaries

If APIs are eating the world, creating API documentation that is informative, succinct, and easy to read is crucial for making your API easy to understand and use. Consistent design decisions, documenting from a user's perspective, avoiding prominent URIs, writing in a suitable format, generating examples automatically, planning for the future, and considering the limitations of tools are key tips provided by Andy Wilkinson, Spring IO Platform lead at Pivotal, to help create RESTful API documentation that users will love. By following these guidelines, developers can ensure their APIs are easy to use and maintain, ultimately driving the adoption of their great ideas worldwide.

API documentation is likened to recipes, essential for making APIs understandable and usable, with Andy Wilkinson of Pivotal offering guidance on creating effective RESTful API documentation. Key tips include maintaining consistency in design decisions and naming conventions, documenting from the user's perspective by aligning with their mental models, and avoiding making URIs the focal point to prevent hard coding issues. Writing should be done using tools designed for documentation, such as ASCIIDoctor, and combining auto-generated examples with manual explanations can enhance usability, as demonstrated by the Spring REST docs project. Additionally, planning for future RESTful developments by considering the Richardson Maturity Model ensures that documentation tools do not limit RESTful API capabilities.