If you’ve had a hard time integrating with downstream APIs 
, I feel ya! To commemorate those efforts and document all the new (maybe not so new) things I learned about API specifications, I present to you a blog post full of integration struggles (maybe some tips too).
Since we’re such a close-knit community and have folks who are probably integrating with some APIs, I’d love to listen to you rant in the comments or just share your learnings and experiences. 
Thanks!
Ah! I wonder if @thefierycoder has an opinion?
I can relate in many ways. From one developer advocate to another, it is really frustrating when developers are constantly running into issues with your documentation or API reference because they are out of date. I encounter regularly, frustrated developers that want to understand why the documentation states something is a string that is actually an object etc.
As a previous API tester, having to validate use cases, having a specification that could be reviewed for logic errors ahead of time with our product team would have been instrumental in ensuring that user stories were not only accurate but robust enough to meet the end user need. Even if that end user is a microservice or another API.
This is great content and context!
Hey @rachael.elizabeth.th,
Thanks for sharing I’m interested to understand if all the issues you went through while integrating also pushed you to explore specifications? Or did you end up using another solution to ease the process?
Previously, my teams did not create API specs in the design phase. We would iteratively change the APIs all of which had to be documented. I proposed using Postman in that situation because our lead backend engineer would require collection updates and documentation as part of the pull review process. Basically we worked around the lack of specs with other processes.
Thanks for sharing @rachael.elizabeth.th. It can be difficult to reverse the process, thinking and designing before implementing 
I like how you can do the spec first and generate everything from it. I just played with this spec a while ago.
https://www.postman.com/api-evangelist/workspace/zomato/api/fe5cc858-a82f-4554-b764-19d86238ab44?version=7e206a1d-43c5-4d2c-a68e-07a0ea43a76d&tab=define
This definition has so much description, it’s just a Generate collection click to generate the documentation collection.