I heard a story this morning while having breakfast with someone at the Venetian before I made my way to the re:Invent registration counter which reminded me of the now infamous secret to Amazon’s API success myth story. I can’t mention the company involved because they are pretty confident they’d never get approval to tell this story publicly, but as I so often do, I still feel it is worth telling even in an anonymous way. Internal groups at this company were having such a problem around coherently discussing the details of APIs between internal groups, that they made a rule that they will not talk with other teams about any API without there being a Postman collection present (ha, Postman mediator) to facilitate the conversation.
There has been several stories on this blog about the problems with emailing API responses between teams, and sending Microsoft Word documents with XML or JSON responses embedded in them. If you work within the enterprise you know that this is a common way to share API responses, and get guidance, ask questions, and generally discuss the details of each API being put to use. Imagine if all of this was banned, and if you had a question about the details of making an API request or parsing the response, it was mandatory to provide a Postman collection of each API request and response in question. Ensuring that ALL the details of the request with a real-life example of the response was present before any discussion would commence. Talk about a game changer when it comes to making sure people were on the same page when it came to discussing some very abstract concepts.
Ensuring team members are all on the same page when it comes to what an API is, let alone the endless number of details regarding query parameters, headers, authentication and other details takes a lot of work. Even if all stakeholders in a conversation are up to speed on the same API, understanding the different contexts in which each API can be executed takes a lot of communication. Why bother? Just bake every bit of that detail into a Postman collection, then share that collection to a workspace team members have access to, or directly provide them a link to the collection, and let the collection do all the talking. GET requests are easier to share, but once you get to the details involved within a POST, PUT, DELETE, or other request, you are going to need to make sure all the headers, body, and other details are present, otherwise the person you are speaking with will be lost—something that is extremely common in the API space, and is preventable using a Postman collection.
I like the concept of requiring all API stakeholders to communicate using a Postman collection. If you have a specific question about why this API request isn’t working, share exactly the same request you are making with me before I will respond. If you are seeing something in the API response that shouldn’t be there, then share the API request with me as a collection so I can see the response you are talking about. There is no reason why we should be going back and forth via email sharing XML and JSON responses—this isn’t the best medium to get our point across. Require your technical and non-technical stakeholders to always provide a Postman collection when they are talking about a specific API and ensure everyone is on the same page before getting to work moving the conversation forward. I love that Postman collections provide this kind of foundation for how we communicate and collaborate around our digital capabilities, making all of our lives easier along the way.
