Better Practices
Published in

Better Practices

Building Typeform’s collection

A Typeform engineer’s guide to automating API documentation using OpenAPI and Postman

Photo by Maarten van den Heuvel on Unsplash

How we built it 🛠

Import current API docs into Postman 📩

Result of importing the collection in Postman

Adapt our internal api-docs to standard format and filter out internal endpoints 📑

  • 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.

Investigate Authorization header issue in Postman 🐛

We wrote our own converter

Endpoints organized by tag and Authorization header

Automate the process to get updates of the collections ⚙

4 steps of the automatic process to add new changes to the Postman collection
  1. A dev merges a change into the api-docs repository, which triggers a build in our continuous integration pipeline.
  2. If the build is successful, the script runs and generates a JSON file with the collection of external, live endpoints.
  3. The script feeds the JSON to our converter to get the collection in Postman collection format.
  4. Another script makes a call to the Postman API to update the collection in our account:
Call to update the Postman collection

What’s next 🛤



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store