What is postman "APIs"?

đŸŒ± Just Getting Started
1

We use postman collections (we hand write api calls in collections for each of our supplies APIs which takes weeks or months), and create environments, but what are “APIs” which are on the left nav? We already have groups of collections and environments (they are called workspaces).
What are the “APIs” section for, and what is the use case?
Thanks!

1 Like
2

Hi @nutmix

The API tab allows you to design your APIs using API definitions.
These links probably describe it better than I could.

Once the APIs have been created, Postman enables you to create ready-built collections that can then be used for testing, etc.

From what you have written, you refer to ‘supplies APIs’ which sounds like they are already built and owned by a 3rd party.
In this case, I would ask the supplier if they have API documentation.
They may be able to provide you;

3

Thanks for the reply. read the links you sent. They seem to require an api definition file. Where does this come from? Then it says it creates a collection, and can import from a collection. So I create a collection, use this to create an api (Which is just a collection?), then push it back to a collection? I am obviously missing something fundamental as I cant see why anyone would do this.

When we want to create a new internal api, we write documentation on our wiki, then we create a new request endpoint in our collection, export the collection to disk, then push the change using git command line, and other devs can pull the new api calls if they need to try them with postman.

4

@nutmix You’re correct, “APIs” in Postman typically start with an API definition. Once you’ve got one you can then generate different collections from it (one for testing, one for documentation etc).

I usually describe it as:

  • The APIs tab is mostly used by API Producers, it allows them to centralise all their resources together, as well as set up some integration (e.g. NewRelic, GitHub).
  • Collections on the other hand are the API Consumer side, where you can go and send request to existing APIs.

If you’re creating new APIs, you may consider starting with an API definition and leveraging the APIs tab in Postman but this will require someone in your team to learn more about API specifications!
Here’s an overview of the API Builder (it has changed a bit but most features stay the same):

1 Like
5

Thanks for this informative reply The guy in the video has a 500 line yaml file in open api 3.0 format. Hand coding such a beast would be extremely arduous. I am used to using things like swagger to take existing apis I have developed in Java and document them, but i would never consider writing hundreds or thousands of lines of xml “first”. Lets say I do have a bunch of java api code, and I have integrated swagger, and I manage to export a file which postman can import, I still cant see why I would want to import this into “APIs”, and not into a collection, as in a collection, I can use postman to hit my api endpoints for testing or for triggering desired events, and i can export the collection and share the export with my team (who can import it as a collection).

6

Hand-crafting a 500 yaml file is work (I can confirm, as I am “the guy in the video” :joy: ), but you need to put that in comparison with the amount of time it may save your engineering team down the line.
This goes into a bigger discussion about the benefits of being API-First, here are some resources you can have a look at if you’re interested:

If you can generate an API definition from your Java code then you may want to import it to Postman as an API to leverage some integrations, e.g.:

  • Git integration: get your API definition and collections synced with GitHub, and use that as your source of truth for all your teams
  • API Monitoring: get results from your APM directly in Postman, and push monitoring results from Postman to your APM

But again, if you as an individual do not see value in importing an API definition in the APIs tab instead of collection, then it probably means you aren’t the right target group for it, and that’s alright! :smiley:

1 Like