DEV Community

Cover image for Creating and Using the Run in Postman Button
Jan Schenk (he/him) for Postman

Posted on

Creating and Using the Run in Postman Button

Hey, what's that Run in Postman button?

Hey there, great that you ask. The Run in Postman button is a way to help others get started with your API. It's an embed-code you can use in HTML or Markdown, that shows an orange button in your document, saying "Run in Postman". Once you select it, it forks the original Collection to your Workspace. It can also include an Environment, so everything someone needs to start playing around with your API is included.

Wait, I understood "embed-code", and I know HTML and Markdown, but what's a collection and workbench, you said?

Workspace. You can compare a Workspace to a physical "workshop" for crafting things. A Workspace keeps all the stuff you need to get an API job done: your tools (Environments), blueprints (APIs), material (requests), instructions (documentation) and also experimental setups (Mock Servers) are included. All that's already pretty advanced, but you'll get there!

Maybe not today, right? What about single requests?

A Collection is comparable with a workbench. It's located in your workshop a.k.a Workspace and you can align all your requests in there the way you need them to be. You can have several Collections in your Workspace, just like you would have multiple workbenches in a workshop.
Now with a Run in Postman button, you let someone else make a fork (not really a copy, let me explain that in a minute) from one of your Collections, so they basically make a snapshot of one of your workbenches (Collection) and have an exact reproduction of that in their own Workspace. You can also tell them which tools (Environment) would be best to use for that project.

Can you show me that Postman button, now?

Sure, here you go: Run in Postman

Hmm, ok. That's it?

The beauty is not in the button. It's just an SVG. You could make it look whatever you want. The beauty is in the functionality. You create it from any Collection you want to promote, including an Environment or not, and Postman takes care of all the backend stuff. You'll be able to embed this Markdown or HTML code in your documentation, your GitHub README.md, your webpage or wherever, and get to know how many people forked your Collection, and how they use your API. They get access to the documentation you included with your collection. All this helps you make the experience of using your API a delight - not a challenge.

Can you show me how to create such a button? Is it automated?

You bet it is. You head over to the Collection you want to share, select the three dot menu from a collection (not a request!) and select "Share".

Image description

An overlay lets you define how you want to share. Select "Via Run in Postman", make it HTML or Markdown, select an Environment to include if necessary, and then copy the code to your clipboard and paste it wherever you want.

Image description

Important to notice, you can only create RIP buttons, that's how we call Run in Postman buttons internally, from your own collections. Any more questions?

Continue this discussion with your own questions in the comments now.

Top comments (0)