Postman JSON to file directory translations

by Hank Lin

Context: Postman is a widely used tool that is useful for API development. A Postman collection is a defined collection that allows for documenting, sharing, automated monitoring, and express complex workflows for API's and their success/failure. Postman collections are expressive enough that I believe API workflows as libraries can be encapsulated within them and be executed by an interpreter (my other project) in any environment or program.

Challenge: The way that Postman currently imports and exports collections is entirely through JSON. This is a problem because when trying to collaborate in a version controlled environment (such as git), the line diffs and changes that are being made will result in merge conflicts or garbage diffs that are hard to collaborators to review and merge together.

Current Solutions(implications):

  • Upgrade to the enterprise tier of Postman product to allow separate accounts to make changes and modification of collections and be able to revert any change using Postman's history feature (does not allow a truly separate workflow for separate changes and merging of everyone's work, changes can happen without a review process)

Possible Solutions(pros/cons):

  • A program that can take in Postman collection JSON and convert that into a folder directory structure with information regarding the collection. The directory structure can also hold additional metadata to allow conversion back into Postman collection JSON to be loaded into the application or be run by Newman.
    • Pros:
      • Allows easier version control diffing and team review process
      • Allows collections to be easily shared and contributed to by users who don't have an enterprise Postman account
      • Offloads Postman application's necessity to hold all the information
    • Cons:
      • A lot of work to write a program that can handle that kind of conversion process
      • If Postman ever decides to change its JSON schema regarding collections, will have to also be updated to accomodate

Solution in Progress: A Rust program that can take in Postman collection JSON and output a directory of folders and YAML files that correspond to the requests in the Postman collection. On the flip side, the program should also be able to take in a metadata file of said output directory and be able to construct an identical Postman collection JSON that can be fed back into Postman.

Business Impact:

  • Consumer win:
    • Consumers would be able to maintain all the power and expressiveness that Postman encapsulates but also be able to version control the changes to collections
    • More simultaneous collaboration changes to a Postman collection can happen
  • Open Source Contributor win:
    • Be able to demonstrate skill with Rust programming language
    • Potentially be involved in growing trend of unification and simplication of API usage in tech
  • Everyone win:
    • Enhanced collaboration and easier documentation with API development