pmac

A CLI tool to manage Postman as code, together with OpenAPI for building well defined APIs that easy to well-specify, validate, and verify with API tests from your repository for scalable applications.

Disclosure 🙏

I just published this package, So I'm consistently working to improve it. So if you have any suggestions or had a bad experience, I would be happy to hear - you can contact by using the Discord channel, or contact with me via LinkedIn.

Roadmap 🗺 🧭

Transparency is an important key, especially for open sources, to help with your decision making wether to use a lib or not. For this reason, I'm working on building a public roadmap for pmac.

Description

pmac stands for "Postman as code", it is a CLI tool and a framework for building efficient and scalable APIs, by specifying your API following the OpenAPI standard that is giving you a set of tools out-of-the-box by itself, including validation based on the specification. Then, after having your specification pmac auto-generated your specification to postman collection, and manages the collection and other Postman entities as code in your repository while helping you to push changes from repository to Postman account, pull changes into the repository, and gives you the ability to manage Postman's entities automatically. pmac uses modern Javascript, is build with TypeScript, and centralize UX for easy and convenient usage.

Philosophy 🧐

pmac built with the recognition of the advantage of using standards and widely known existing products to fit for many different use-cases scenarios, and also to be easy to migrate to.

In other words, not aiming for inventing the wheel, but for connecting the dots.

In today's competitive world, the number of requests grows exponentially, clients have a very high standard for digital products even unconsciously, and resources are expensive, APIs should be built with strong fundamentals for standing the demand for scaling up.

Having this understanding in mind, pmac aims to be the "glue" of 3 domains any API required to manage - Specification, Validation, Verification.

• Specification with OpenAPI (v3)
• Validation by using the specification
• Verification by auto-generating & managing API tests with postman as code in your repository

Change log 🐾

View the changelog.

Features 🦚

• Integrated with Postman API, using an API key, you pass to pmac
• Priortizing user experience using
  • Supports auto-completion and help guides by using oclif CLI framework
  • Enables user inputs using inquirer
  • Indication of the step in a process using listr2
• Postman Collections supported commands
  • Pull - into repository from your PM account
  • Push - into PM account from repository
  • Create and Update automatically from your OpenAPI spec yml
  • Delete - both local (repo), and remote (PM account)
  • Execute - run Postman collection fully integrated with newman
    • support all its feature, including cli, html,htmlextra,json,junit reporters
• Postman Environments Commands
  • Create, Delete, Pull, and Push
• Postman Workspaces
  • Create - Create new workspace and push into PM account
  • Pull - Pulls a workspace into your repo
  • Delete
  • Fetch - fetch changes from the existing workspaces in repo
  • Pull all - pulls the whole postman account
• With Collection.Execute it is possible to run pmac in CI/CD pipelines
• Auto-generated Postman collections out from OpenAPI specification - Works with openapi-to-postmanv2 under-the-hood
• By managing Postman entities you get all Postman features out-of-the-box, convenient UI, tests, pre-request-scripts, EVERYTHING.

Getting Started

1. Installation, use npm or yarn

npm i -g pmac // or yarn global add pmac

1. Generate a Postman api key

   1. To create pull and push actions

2. Commands guide

   1. use pmac help and pmac <command> --help to see a guide for all commands.
   2. Also, you can use the generated commands docs here

3. Write your API openapi specification

   1. Learn more about openapi with the official docs
   2. Use the Swagger Editor

4. How pmac manages its workpsaces

   1. By decoupling pmac workspaces from pm workspace, which means they are different things!
   2. Although the workspace resources, like collection, environment, etc., are currently similar.

5. See the pmac file tree to understand better how pmac works!

6. Use pmac official docs (very soon...)

License

pmac is MIT licensed