Episode 387: Abhinav Asthana on Designing and Testing APIs

Sync Challenges

API documentation often struggles to stay in sync with code changes, posing significant challenges for developers. Abhinav Asthana explains that while theoretically, documentation should update automatically with code changes, practical issues arise when the developer experience diverges from the codebase. Teams must establish a consensus on managing API changes, such as using pull requests or other systems to review and provide feedback 1.

Keeping things in sync is a hard problem.

--- Abhinav Asthana

He suggests using API schemas as a source of truth, which can be checked into repositories and used to generate developer portals, ensuring consistency and reducing the risk of exposing insecure APIs 2.

   

User Focus

Creating effective API documentation requires a user-oriented approach, focusing on how developers will interact with the API. Abhinav Asthana emphasizes that good documentation should be written from the user's perspective, not just describing the API but showing how to use it effectively 3. This approach increases the likelihood of API adoption and satisfaction among developers.

Good documentation is not what I created, but how somebody would consume what I created.

--- Abhinav Asthana

He also highlights the importance of involving external perspectives in documentation for larger APIs to ensure clarity and usefulness, suggesting that practices should be geared towards accommodating inevitable changes 4.