Add an option to "Update Collection" generated from the APIs tab

[tmdoit-zz]

Is your feature request related to a problem? Please describe. When updating collections from API schema, all examples are lost - you need recreate all examples from zero - this kind of development is useless if you prefer develop collections from API spec.

Describe the solution you'd like Add option "Update Collection" next to "Generate Collection" in APIs tab

Describe alternatives you've considered After every update add manually all examples.

IMHO it's priority for APIs new feature you released.

[arlemi]

@pankaj-cashify You should see a Click to validate button next to the collection you've previously generated, you need to navigate to either the Develop, Test, or Observe tab to see it.

[pankaj-cashify]

@arlemi sync is not working for me. I have attached a sample OpenAPI doc. I tried updating request parameter app_version3 to app_version5

test.json.txt

[abhinaba-ghosh]

Hi @pankaj-cashify , we have been able to reproduce what you are facing. We have opened a new ticket to track the issue. We will be posting updates once we have more information.

[gauravsoni1]

I see this issue has been closed, what would be the workaround for the following. Suppose in v1 of Spec , i had defined 2 example. Later on I added another example to the same version. Is there some way to refresh the collection so that it would reflect the new spec ? Perhaps the right way would be a version update and a new collection ?

[arlemi]

@gauravsoni1 This is exactly what this feature allows you to do, once you have generated a collection you can keep on updating it as you update the schema. You can see an example of how to achieve that in https://github.com/postmanlabs/postman-app-support/issues/6722#issuecomment-691020293, and learn more about it in the Learning Center: https://learning.postman.com/docs/designing-and-developing-your-api/validating-elements-against-schema/#updating-api-elements

[molteninjabob]

@molteninjabob thanks for bringing this up. We're putting in some configuration options so that you're able to select how you want your query params, request body etc to be generated. I'll post here what I have an update on this. If there's anything else that you'd like to see in the generate/update flows, do let us know!

@sankalp0o I see that this issue has been Closed. Regarding the configuration options you mentioned, do you have a reference to another ticket where this is captured? I'd hate for this to get lost because this issue was closed.

[arlemi]

@molteninjabob We've added more options to collection generations in Postman 7.30 which was released beginning of August. Here's some more info from the release notes:

"You can generate collections from your API specification using the Postman API Builder. Though, we've listened to some of your feedback around being able to customize how these collections are generated, therefore from 7.30 when generating a collection you can choose:

• What should be use for the naming requests: url or fallback (description, operationid, or url)
• The indent character: spaces or tabs (we all know tabs is better)
• Whether to collapse the folder that have only one request or not
• Whether to optimize for conversion or not
• What should be used for Request and Response parameter generation
• If the folder organization should be using Paths or Tags

This configuration options are available when generating a collection from the schema, Define, Develop, Test, and Observe tabs."

[JerryChin]

I'm using postman for API documentation purpose, the API schema changes rapidly, but there's no way to update the linked collection.

[cdolan92]

@jerry Chin it seems to me that supporting a merge or other method with the Collection is not the standard use case for Postman. We tried making this work off and on for over a year, and are now moving away from postman to host our api docs because even though we generate OpenAPI compatible files, Postman performs some vendor lock in with a 1 way migration to Collections.

Once your schema (and particularly your markdown or other content) is in a collection, it’s very funky and hard to update it in any meaningful way other than to hand type it out again.

---

From: Jerry Chin @.> Sent: Wednesday, August 18, 2021 11:44:07 PM To: postmanlabs/postman-app-support @.> Cc: Charlie Dolan @.>; Comment @.> Subject: Re: [postmanlabs/postman-app-support] Add an option to "Update Collection" generated from the APIs tab (#6722)

I'm using postman for API documentation purpose, the API schema changes rapidly, but there's no way to update the linked collection.

— You are receiving this because you commented. Reply to this email directly, view it on GitHubhttps://github.com/postmanlabs/postman-app-support/issues/6722#issuecomment-901585661, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AAQISJUQS5HLIINGQVIHT2TT5R4YPANCNFSM4HYUI2EQ.

[dengshenkk]

What is the status of this case ?

[arlemi]

@dengshenkk This is already released, check out this comment: https://github.com/postmanlabs/postman-app-support/issues/6722#issuecomment-647667330

@JerryChin What do you mean there's no way to update the linked collection? Are you not seeing the "Click to Validate" option? Giving a bit more details would help.

[Kazmirchuk]

is my understanding correct that this feature can be used only with OpenAPI v3? Unfortunately, I'm stuck with OpenAPI v2

[arlemi]

@Kazmirchuk Correct, we will likely add more over time but I don't have any insights into that at the moment.

[AlissonRS]

@arlemi I see the "Click to Validate" option, but I get "Unable to validate" because the schema is larger than 5 MB (it's indeed a large schema but it's actually around 2 MB, not 5). Is there a workaround for this?

Unfortunately I do not own the schema, otherwise I'd split it into smaller ones, but I really wanted to be able to Update this collection without losing variables/headers and other stuff in place in the existing collection.

[mklueh]

If it is not possible to update a collection, what is the correct workflow then if an API changes?

Let's say, you have multiple services and imported their specs into collections. You have created multiple tests, and configured variables, and now the API changes. What to do now?

Is it like this:

1. Create a fork
2. Import the API a second time into a new collection
3. Copy everything from the new collection into the old collection
4. Delete new collection
5. Merge back

What about tests / variables for example?

[arlemi]

@AlissonRS Can you please open a new ticket to raise that issue? If the schema is smaller than 5MB you should be able to update the collection. If you're able to provide the schema it would also be super helpful!

@mklueh If you have the API definitions, why are you not using them to generate the collections, and then update them as the API definitions evolve? I'm not sure if I understand your use-case here.

[mklueh]

@AlissonRS Can you please open a new ticket to raise that issue? If the schema is smaller than 5MB you should be able to update the collection. If you're able to provide the schema it would also be super helpful!

@mklueh If you have the API definitions, why are you not using them to generate the collections, and then update them as the API definitions evolve? I'm not sure if I understand your use-case here.

@arlemi I'd love to do that, but I don't see any option to update an existing collection based on a new OpenAPI definition in Postman. Maybe I'm just overseeing it? I was asking for a kind of workaround based on my assumption, that there isn't such an option.

[arlemi]

@mklueh As long as the collection has originally been generated from that spec (and that they are linked) you should be able to do it. Have a look at the documentation here: https://learning.postman.com/docs/designing-and-developing-your-api/validating-elements-against-schema/#validating-elements

[mklueh]

@arlemi thanks, this brought me one step further towards my goal. Not sure what you mean with "linked", but I've imported it with the import assistant by pasting my openapi spec URL. When I press validate, it does not pick up the latest spec the API provides through its spec URL, but rather the old one I've used during the import.

The validation works fine if I copy and paste the new definition into the editor of the definition tab, but this can't be the right way I guess.

[arlemi]

@mklueh Glad you got it working! And it is the expected flow, when you import an API definition it's a one time import and it doesn't keep a reference to the original link. If you'd like to have your API definition synced with your Git repo (Github/Gitlab/Bitbucket) have a look at this: https://learning.postman.com/docs/designing-and-developing-your-api/versioning-an-api/#using-an-external-git-repository

[cavator]

so a big company like postman, could not create a feature to "watch" or update the API? in 2 years? that could not be serious. or can and I'm missing something? and i don't want to connect to some repo, i want it to watch my local file that i set when create the API it's not that hard create this, even more in 2 years of issue

[cavator]

someone could please open this issue again, it's not even close to be closed.

[arlemi]

@cavator This is about updating a collection that was generated from an API in Postman. Looks like you're looking for something else so I'd recommend creating a new issue and provide as many details as possible.

[cavator]

@arlemi it's not because because i said "watch", that you will pretend i'm talking about something else, "or update the API" i think we talking about the same thing, update the collection generated from an API in postman, people now are 2y updating 1 line of the mutation or query and deleting and recreating the API. so please re-open this issue, like i said, it's not even close to be done. and i can't belive a big inc like postman is taking 2y to add 1 button, and still acting like its all ok

[mklueh]

I agree. The workflow would be much nicer if we could tell postman to re-fetch the new schema and get a git-like diff between the previous and new schema provided, to decide if we want to accept the new schema entirely or merge. Then Postman could automatically create a new API version based on the version provided in the schema.

It's not that the current workflow won't work, but the auto-updating feature would be more intuitive and less of a hassle if your API gets frequently updated. This is honestly something I was expecting to happen when I used Postman for the first time until I found out that manual work has to be done.

[arlemi]

@cavator Check that video from 5:40 as it shows the update flow in Postman: https://youtu.be/BUZiRtGRHj0?t=340

If you're not seeing this you might want to check if your version of Postman is up to date (latest is 9.7.0).

@mklueh Sounds like you're interested in auto-updating a schema in Postman from a schema in Git (Github/Gitlab...) rather than between a schema and a collection. If that's the case I'd recommend watching this video and/or reading this blog as they show how you can integrate with GitLab/GitHub/Azure DevOps and get diffs of changes between your repo and your API in Postman. If you have more questions on this I'd recommend chiming in on the community forum instead as you'll get more eyes than on a closed issue here. 😅 https://community.getpostman.com/

[tbcarver]

Just to validate your workflow for API schema first development.

1. Create an API Schema and make some changes.
2. Click Generate Collection button (well placed on the upper right above the tabs on the api schema page). Now I have a linked collection.
3. Make edits to the API Schema.
4. Ignore Generate Collection (pretend it doesn't exist), go to the documentation tab, look to the right for validate schema button, click button and wait for failure, click Review Issues button, on the sync collection to schema page, check select all and then hit the Confirm Changes to the Collections button.

Wow you nailed this common workflow, not overly engineered or confusing at all. It was real obvious after digging through docs, this post, videos etc. Have you considered hiring a UX expert? Also, are you recommending not using the API Schema feature because clearly you have wedged this feature into collections like some type of ugly side car.

Sorry about the sarcasm, but I think you should consider real world workflows before releasing your product. BTW people do updates to the API Schema pretty often, just fyi.

[mklueh]

@cavator Check that video from 5:40 as it shows the update flow in Postman: https://youtu.be/BUZiRtGRHj0?t=340

If you're not seeing this you might want to check if your version of Postman is up to date (latest is 9.7.0).

@mklueh Sounds like you're interested in auto-updating a schema in Postman from a schema in Git (Github/Gitlab...) rather than between a schema and a collection. If that's the case I'd recommend watching this video and/or reading this blog as they show how you can integrate with GitLab/GitHub/Azure DevOps and get diffs of changes between your repo and your API in Postman. If you have more questions on this I'd recommend chiming in on the community forum instead as you'll get more eyes than on a closed issue here. 😅 https://community.getpostman.com/

No, that is not what I meant. I meant "git-like diff" for the changes coming from an OpenAPI endpoint

The way I'd like it to be:

1. Make your API changes and raise the schema version
2. Tell postman to reload changed schema, auto-create a new API version based on the given schema version, then update the collection.

[eladchen]

Correct me If I'm wrong, but updating the example of a property is not detected when validating the documentation...?

I'm using the v9.13.0.

Is there any docs on what type of changes are detected when "validating" a documentation/collection?

[arverma77]

@arlemi sync is not working. I see that when we update the API name , only this particular change is taken into consideration. But if I try updating request parameter, the sync doesnt work. A ticked was logged for this issue in year 2020.

https://community.postman.com/t/user-feedback-updating-api-elements/13308

Can you please let me know how to sync a change to an attribute in API file to the collection.

[arverma77]

Correct me If I'm wrong, but updating the example of a property is not detected when validating the documentation...?

I'm using the v9.13.0.

Is there any docs on what type of changes are detected when "validating" a documentation/collection?

Only the attributes which has property required=true is validate for any change. Optional attributes are currently not validated against the API changes.

[liviusighiartau8x8]

Is there a way to sync Postman collection with OpenAPI/Swagger? I think this was raised in the past, has something been done for it?

[n4j1Br4ch1D]

No Solution Yet?

[arlemi]

Hey everyone,

At the moment it's not possible to update collections that have been generated from an OpenAPI definition in Postman v10 through the UI. We're working on a newer version of the feature that should fit better in the flow of an API producer.

While we re-implement it, you can still use the Postman API to update your collections, see more info here: https://www.postman.com/postman/workspace/postman-public-workspace/request/12959542-b5acf70c-7635-4d64-b17b-d4b2824c4a39?ctx=documentation

I'm re-opening this issue and we'll keep posting updates here as we make progress. cc @shashankawasthi88

[AmirHmZz]

Any updates on this?

[shashankawasthi88]

Hey @AmirHmZz we are actively working on this issue and will update the thread as soon as we have an update for you folks. Thanks.

[Bandgren]

@shashankawasthi88 is this weeks, months, half a year away? Would be good to have a rough estimate so we can either put time into use the API endpoint or just wait for it to be implemented back! :)

[shashankawasthi88]

@Bandgren this is in our short-term road map. I can not comment on the exact timelines yet, but we are actively working on the feature request.

[sc-atompower]

With the integrations to Azure API Management, etc, we are actively looking forward to this.

[Matvii-Boichenko]

On project we are using AWS APIGateway & Postman as documentation, feature with "git-like updating" of collection from imported OpenAPI Definition of Postman API would be VERY Handy

[Bandgren]

@shashankawasthi88 we are now almost 2 months from my original query. This is a "check-in" how is this feature going? Any progress you can update us on?

[shashankawasthi88]

@Bandgren and all, this feature is being released in our upcoming March 15th release. We look forward to you using and providing your valuable feedback on the same.

[Bandgren]

@shashankawasthi88 Thank you so much for the update, and that is some really great news!

[Bandgren]

@shashankawasthi88 was this released with this release? Cant find anything in the release notes, have tried to update a openapi spec in both the mac app and in chrome and cannot find any "update collection" button anywhere?

[fmiqbal]

@Bandgren yes it is released,

the update button is a bit hidden though, it only visible when there's schema change, and it run in background, so wait a bit after you save your change in your schema, and this should pop out to the side of your collection

[arlemi]

@fmiqbal Good catch! It has been released in the last version and is currently being rolled out to users over the next few days.

You can read more about how to update the collections here: https://learning.postman.com/docs/designing-and-developing-your-api/developing-an-api/adding-api-elements/#keeping-a-collection-in-sync-with-an-api

And we'll soon be releasing a video demonstrating how to do it too, I'll post it here when it's out!

[Bandgren]

@fmiqbal & @arlemi thank you so much! Looking forward to start using it!

[Alchoder]

From what I understood, automatic synchronization is only available when you have Enterprise workspace ?

[shashankawasthi88]

@Alchoder this is available for all.

[AmirHmZz]

@shashankawasthi88 I don't use postman enterprise and still I cannot figure it out. Can someone make an step to step guide to make it work?