On Monday evening, Caplin was delighted to host the first Write the Docs London meetup of 2020 at our offices in Leadenhall Street.
There was a good turnout to hear Kin Lane (@kinlane) speak about using Postman to generate API documentation. Kin is the chief evangelist at Postman, and the author of the API Evangelist blog. He’s a regular presenter at talks and conferences. He has presented at a workshop for the European Commission’s APIs for Digital Government study, and on Monday evening he was fresh from speaking at the GDS Tech Talk on Interoperability and Open Standards.
Kin began with an introduction to Postman. The majority of Postman’s 8 million users are familiar with Postman only in its capacity as an API client; first as a Google Chrome extension and now as a native desktop client for Windows, macOS, and Linux. Postman is, however, much more than this. It is a full API development environment, with an ambitious roadmap for the future.
Kin’s presentation took us on a tour of Postman’s features, beginning with creating an API request and receiving a response. Postman adds value here by enabling you to present the response graphically with custom visualizers, but it’s when you group requests into collections that Postman’s wider feature set really becomes apparent.
Collections of requests are the fundamental building block for collaboration in Postman. Collections can be documented, shared, forked/merged, and published. Kin showed us how easy it is to generate documentation for a collection of requests. He started with a simple example and then embellished it by adding example values, Markdown content, environments (authentication keys and variables), and versioning. The collection can be shared privately with team members, or published (at team level) to the Postman API Network or made accessible to the Postman community as a template.
Lastly, Kin introduced us to a new feature, recently out of beta. Postman allows users to generate a collection from an API specification written in OpenAPI (Swagger), RAML, and other formats. This feature is key for integrating Postman with API development lifecycles, where the specification is kept in source control and treated as a single source of truth. API specifications develop over time, and Postman provides tools to identify where generated collections deviate from the specification as it evolves.
It was an engaging talk and a great start to the year for Write the Docs London. Many thanks to the Write the Docs team and Kin Lane, and I look forward to attending more Write the Docs talks this year.
