????We thought that our experience with building a Postman collection might be useful for other companies that want to streamline first contact for potential API users.
We hope other devs will benefit from learning about our process and the advantages of automatically building our Postman collection from documentation, instead of manually creating and maintaining it.
How we built it ????Import current API docs into Postman ????Our internal APIs are documented in OpenAPI 2.
0, a standard specification to describe REST APIs.
We maintain this documentation in the api-docs repository, which every engineering team updates with every change they introduce to the APIs they own.
Postman allows you to create collections from several formats, and one of them is OpenAPI.
So our first step was manually importing our current API specification into Postman to see what would happen.
Great news — it worked perfectly!No, that’s not actually what happened.
At first, it looked like there weren’t any errors, and the collection was successfully created in Postman.
But after taking a closer look at the endpoints, we saw some odd things: our internal endpoints were also imported, some parameters weren’t correctly converted into Postman variables, and we couldn’t see any trace of authorization headers…among other things.
Uh-oh.
Result of importing the collection in PostmanAdapt our internal api-docs to standard format and filter out internal endpoints ????So the next step was giving some love to our new collection.
First, we identified the format issues in our specs that caused missing information in the imported collection.
We corrected these issues to comply with the OpenAPI standards and make the collection work nicely with Postman.
Specifically, we removed unnecessary quotes surrounding some endpoints and moved the parameters definition into the proper place.
These small changes solved most of the issues so that all the URL parameters displayed correctly in Postman.
After that, we needed to do some processing to filter out the internal endpoints and export only the public endpoints for the collection.
To do this, we used OpenAPI extensions, which are custom properties you can add to a specification.
We added these extensions:x-visibility: indicates if the endpoint is public or for internal use only by specifying the value as EXTERNAL or INTERNAL.
x-status: indicates if the endpoint is ready by specifying the value as LIVE or IN_DEVELOPMENT.
Then, we wrote a JavaScript script to check the x-visibility and x-status properties and export only the external and live endpoints:Feel free to re-use this script with your own OpenAPI spec using the same custom properties we defined.
Using this process we only maintain one OpenAPI file as our source of truth.
And we can easily add or remove endpoints.
Investigate Authorization header issue in Postman ????To use the Typeform APIs, you need to pass your personal access token in the Authorization header for every request.
We specify that requirement in our OpenAPI spec as follows:Despite trying several different approaches, we weren’t able to make the Authorization header show in Postman.
We tried importing in YAML and JSON formats, converting our OpenAPI 2.
0 spec to OpenAPI 3.
0 and using the new security definition format, and converting to Postman’s own JSON format using the OpenAPI-to-Postman and Swagger2-to-Postman libraries.
None of these solutions worked completely.
But we didn’t give up…We wrote our own converter ✍We decided to try to get the Authorization header to work using Postman’s own collection format, so we wrote our own converter from OpenAPI 2.
0 to Postman Collection Format Schema.
This way, we could inject the Authorization header in every endpoint of the spec, following Postman format.
We created a JSON file describing a test endpoint that included the Authorization header and imported it to make sure it solved the problem.
And it worked!.????This also gave us the opportunity to reorganize the endpoints with tags instead of path structure.
Using tags, all of the endpoints are organized according to the domain they belong to (such as forms, responses, and themes).
The tags are similar to the way we have the endpoints organized in our dev portal: Create, Responses, and Webhooks.
Endpoints organized by tag and Authorization headerAutomate the process to get updates of the collections ⚙We needed a way to keep the collection up-to-date with every improvement to our APIs.
We already knew that doing it manually is not a great solution — it adds work for developers and usually leads to outdated information.
So the last step of the process was to automate the collection generation and updates using the Postman API.
Here’s how it works:4 steps of the automatic process to add new changes to the Postman collectionA dev merges a change into the api-docs repository, which triggers a build in our continuous integration pipeline.
If the build is successful, the script runs and generates a JSON file with the collection of external, live endpoints.
The script feeds the JSON to our converter to get the collection in Postman collection format.
Another script makes a call to the Postman API to update the collection in our account:Call to update the Postman collectionWhat’s next ????This process took about 1 week, with one dedicated developer (yours truly) working with support from the rest of the dev team as needed.
As for next steps, we are keeping track of how many people click the Postman collection button on our dev portal — an average of 16 per week so far.
We’ll keep an eye on that tracking data to confirm people are using the collection.
We’ll also need to monitor the process to make sure our API updates are always incorporated in our Postman collection.
Other possibilities include making our custom converter open source or contributing to Postman’s official open source converter to make it work with tags.
If you have any suggestions or feedback for us, please share it here.
.