Confused about APIs in Postman and how they "sync" to Postman Cloud

[pcolmer (Philip Colmer)]

I’ve imported an OpenAPI document into my team workspace. That has created a collection, and an entry under APIs with the full OpenAPI document.

I’m trying out the contract test generator and I’ve got to the point where it is complaining about parts of my API document. For example, it wants schema entries to start with an uppercase letter.

So I edit the API definition in the Postman app to fix that issue and save it. Re-running the contract test generator, however, still complains about the issue.

I then look at the web-based version of the team workspace and it does NOT show the edits I’ve made. So I go back to the app, push the changes to the synced git repository, then go to the web browser and pull the changes.

The contract test generator STILL complains.

Looking at what the generator is doing, it is calling GET https://api.getpostman.com/apis/:apiId - if I call that API myself, it looks like it returns the original API schema that was imported into Postman. It does not return any of the edits I’ve made.

So how does that version get updated? What steps am I missing out when I edit the schema in the Postman app?

Edit to add that I’ve now tried publishing a version from the Postman app but that hasn’t helped either.

[houssem-gharssallah]

Hi @pcolmer,
Interesting issue. Support in Contract Test Generator for Git based APIs only came on 2024-08-15. Please make sure you are using the latest version of the collection.

The generator requires a version of the API to be published. So, you are definitely on the right track.

To my knowledge, there is no difference between the Desktop and Web (in fact, since v10, the Desktop app is a wrapper for the Web app).
Since you are using Git, the published version will use the contents of the checked-out branch in Postman (Actually, you can’t publish branch content if there are pending changes in the branch).

I hope this helps.

[pcolmer (Philip Colmer)]

@houssem-gharssallah thank you for your reply.

I am definitely using the latest release of the Contract Tests generator. As far as I can tell from the code, it tries three different ways to retrieve the API schema for testing:

1. From the value in env-schemaUrl. Unfortunately, I can’t use this as the moment because the schema file is in a private git repository.
2. If that value isn’t set, the code tries to get the schema from Postman, in one of two ways. It starts by calling GET https://api.getpostman.com/apis?workspaceId={{env-workspaceId}}. If there is a value for env-apiId, the code checks that the API exists in the response from that API call. If there is no value, it simply uses the number of specified APIs against the response from the API. The outcome of that call is to set coll-apiIds to an array of API IDs.

The next step is to set coll-apiId to the first API ID from that value, saving the rest back to coll-apiIDs. GET https://api.getpostman.com/apis/:apiId/versions is then called. For my API, I get pretty much an empty response back:

{
    "meta": {
        "limit": 10,
        "total": 0
    },
    "versions": []
}

In that scenario, the code tries to use the value from env-apiDefinitionId to get the schema. It does that by using GET API Schema (rather than GET Current API Schema). GET API Schema actually fails because the workspace is linked to git, so the suite then moves on to Get API Schema (v9 fallback) which pulls the schema from GET https://api.getpostman.com/apis/:apiId … and this is the one and only version of the schema that gets stored on Postman when I import from GitLab.

So my first question is what does it take to publish a schema to Postman? While linking a Postman workspace to a git repository is useful for using git as the source of truth, as I’ve shown above, the contract tester does not look at the schema stored in the workspace - it either pulls it from a user-defined URL or it pulls it from Postman, and I cannot find any way to update the schema that is stored on Postman. It seems to be created initially when I import into the Postman App, but never gets updated after that.

[houssem-gharssallah]

Yes, per latest Contract Test Generator update, for Git based APIs you need to publish the spec by clicking the publish button located on the side screen.

• Add a version label
• Add a release description
• Click Publish

Note: per my experience with Git based APIs in Postman,

• You cannot have any pending changes in your branch for publish to be enabled.
• Your API definition needs to be valid. Make sure you don’t have any syntax issues.
• There is no difference between the Web and Desktop version of Postman when publishing… however Web version seems more reliable.

This link Publish a version of your API for consumers | Postman Learning Center should demonstrate how to publish.

[pcolmer (Philip Colmer)]

Thanks, @houssem-gharssallah. I think I managed to confuse myself by specifying a definition ID on the contractor generator environment and then wondering why I wasn’t seeing any schema changes when I published a new version from the Postman app.

I’ve now removed the definition ID value and publishing works as expected.

Thank you.