New Postman Integration with AppMap: create and manage always-accurate collections

This is a guest post by Pete Cheslock, head of growth and community at AppMap.

Postman users know that API-first is always the best, and many are already using its API documentation tool to update docs based on their Postman Collection. But not everyone is lucky enough to work in that world, and plenty of teams manage legacy applications with APIs built without documented definitions.

Engineers working on products that were not built API-first face the daunting task of creating these API definitions by hand, using techniques like reverse engineering and tiresome, error-prone code reading.

AppMap is an open source tool thousands of developers use to visualize their application’s runtime behavior. Unlike static analyzers, AppMap records how an application runs and uses that information to find design flaws, security holes, and performance issues.

AppMap can automatically generate OpenAPI definitions for an application by recording its runtime behavior and is aware of all the API calls and their schema. It uses this data to automatically generate OpenAPI definitions for an application, ready to import into Postman Collection. No need to manually write API definitions!

Automating the big first step that nobody enjoys

AppMap automates the creation of OpenAPI definitions, and does so instantly. Engineers can add the AppMap extension to VS Code or JetBrains or run AppMap from the command line. AppMap monitors the application running on the developer’s machine and records all its API interactions.

Once AppMap has recorded the application’s runtime behavior, a single action generates its entire set of OpenAPI definitions. This can be done right in the code editor where the engineer works. For example, in VS Code:

The same command can also be run on the console:

$ npx @appland/appmap openapi

This single, simple command saves hours of valuable developer time! Thanks to Postman’s support for importing OpenAPI definitions, the convert function takes in your OpenAPI definitions (YAML/JSON) and converts it to a Postman Collection. This guarantees that the Postman Collection will be 100% accurate since it is derived from how the API behaved at runtime.

Automatically verifying API compliance

Having an OpenAPI specification with platforms like Postman is critical for the ongoing safe development of APIs. AppMap can automatically check that all HTTP client requests that reach an API correctly conform to the API specification.

Without a tool like AppMap, verification like this is slow, error-prone, and tedious.

Reviewing API changes in PRs

Schema changes are extremely important to check during code reviews. A code change that inadvertently removes a field or causes unexpected structural changes could wreak havoc. These can sometimes be hard to detect by reading code diffs within pull requests, as schema is often generated automatically from object definitions, making the API impact of those changes non-obvious.

AppMap can automatically generate OpenAPI specifications of application behavior while the changes are sitting on a branch and awaiting human review. The reviewer can then compare the production API spec on the main branch to the one on the branch and quickly see the API-level impact of the proposed changes.

Making API documentation updates a breeze

API documentation can sometimes lag behind production API changes. Developers like to move fast and are usually under pressure to release new features, but not all developers are keen to write documentation. That can lead to API documentation falling behind and not accurately describing its actual live behavior, which is a real pain for anyone consuming that API.

Since AppMap can automatically create always-accurate API documentation in Postman, that lag can be massively reduced. The same diffs that were used to assist code reviewers in seeing what API changes are on a branch can be used to help the team make the corresponding changes to their online API documentation in their pull request.

AppMap + Postman = A winning combination

AppMap allows developers to move to an API-first mode in almost no time. By creating OpenAPI specifications and updating them automatically in Postman, teams using AppMap can leverage all the valuable features in the Postman API Platform.

You can start using AppMap today by downloading it now from appland.com.

Watch and learn