from Hacker News

Share Specs, Not Execution

by prash2488 on 7/22/24, 10:11 AM with 1 comments

• by prash2488 on 7/22/24, 10:11 AM

  I've spent time on both sides of the API divide – consuming as a mobile dev and producing as a backend dev. This experience crystallized a key principle: share specifications, not execution details. I've written about how this plays out in the real world, especially when juggling tools like Swagger and Postman.

  The post covers - The inherent tension between Swagger's spec-focused approach and Postman's execution flexibility - Real-world consequences of over-sharing execution details in API documentation - How our team adapted our API development process to better adhere to this principle - Thoughts on what an ideal API documentation tool might look like, combining the strengths of both approaches

  I'm curious to hear from the HN community: How do you balance sharing API specs without getting bogged down in execution details? Have you found effective ways to use Swagger and Postman (or other tools) together?