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.

[tmdoit-zz]

Sorry for confusion, now I see that response examples are generated from API spec.

[saivan]

But I still think this is probably valid, unless I missed something. What about keeping any tests we wrote in a collection?

[tmdoit-zz]

For me the point is to create API spec with examples and then based on it, generate collection - API spec first approach. Currently one missing feature is to generate from spec more than one example if response has more than one possible returned value per status.
If I understand well, you are talking about collection first approach - generating API spec based on collection?

[saivan]

Well. I was going to use postman for my tests. So you generate the openapi file; then make a collection from it. After that, write tests in postman. It would be good to not have to lose all of your tests when you want to change the openapi file.

[preethammavin]

@saivan thanks for the feedback it is a valid use case, will keep it as a feature request

[tmdoit-zz]

@saivan now I get it - tests, not examples 🙂

[bikash8gupta]

The tests are deleted when a generate collection is applied. We definitely need a update collection because all collections have test suites in it and they are not kept when a new collection is generated.
Till then API beta is not of any use. Why I will keep maintaining API specification as well as collection from two places.

[hilary]

What's the status of this issue? I would also like to use Postman API spec first. Without an 'Update Collection' option, the 'Generate Collection' option is useless.

Generated specs better than nothing, but nowhere near as good as authored specs. I really don't see the point of 'Generate Collection' as it stands. Perhaps you could explain a maintainable workflow that used 'Generate Collection' and did not use 'Update Collection'?

[sankalp0o]

@hilary @bikash8gupta @saivan thanks for reaching out!

Collections and specifications (any of them) are very different from each other and at this point, we're unable to update a collection from the spec which can reliably work 100% of the time. That being said, it's not completely impossible depending on what has changed in the spec and how much has the collection evolved. There are solutions that can work in some of the cases.

I request you to tell us the use cases that you have for updating the collection. What are you changing in the spec and how you imagine the collection to be updated?
E.g. I'm adding new endpoints to the spec and I expect new requests being created inside the collection following the correct folder structure.
E.g. I'm updating the descriptions for one of the endpoints and I expect the new description to replace the existing description in the collection request.

This will help us design a better solution! Please also let me know if you're open to getting on a quick call to understand your use case better.

[dvdvdmt]

I'm adding new endpoints or changing existing ones and I expect that different variable values such as baseUrl, authToken etc. will preserve in the collection settings.

[arlemi]

@sankalp0o Similar ask on our community forum: https://community.postman.com/t/automatically-sync-openapi-swagger-spec-to-collection/8551

Mostly, users are concerned about losing their tests and variables every time they regenerate the collection from the schema.

The only concern I have with importing the swagger spec each time is that our test and variables will not be maintained, unless I’m missing something.
I believe even a 1 way sync that would update your Postman collection each time a change has been made to the swagger spec would be very useful.

I'll ask for more feedback if possible.

[andmoredev]

We use the Collection that gets generated by the API only for Documentation purposes so for my use case a full overwrite is completely acceptable.
We keep our Test collections separately so that we can run tests for failures as well which would not be covered by an Open API definition file.

[hilary]

Even though I'm defining security in the spec, no auth is generated for the collection. That means I have to add auth to the collection after the fact. If generation were more complete, the lack of update wouldn't be as bad a problem.

We're primarily adding new endpoints, but occasionally deprecating existing ones. We're also updating documentation.

[tmdoit-zz]

Only difference between "Update Collection" and "Generate Collection" will be that "Update Collection" will recover tests written for defined collection endpoints. I use word "recover" because I don't see for this use case any reason to just not generate fresh collection from API spec and attach tests using collection endpoints as reference. I think that this way of solving problem will keep implementation of this feature simple.

---

UX:
Use case: I want to update collection to keep written tests for collection endpoints

1. I click button "Update Collection"
2. In popup that appears I select via drop down list (API spec children) collection which I want to update
3. Postman updates collection preserving tests defined earlier for certain collection endpoints

Comments:

1. In popup windows information what collection update means

---

If I want to generate new, fresh collection without preserving tests I will use "Generate Collection"
If i want to generate new, fresh collection with endpoints tests preserved I will use "Update Collection"

Preserving variables could be solved same or similar way I think.

This should make sense for API spec first approach.

[tank104]

+1 for this - especially when prototyping - its cumbersome. Right now I use Swagger, then when happy add it to Postman. Would be nice to skip Swagger step.

[fabiendeborde]

I'm adding new endpoints or changing existing ones and I expect that different variable values such as baseUrl, authToken etc. will preserve in the collection settings.

Pretty much this use case.
If I update the OpenAPI file (which is the origin of my collection), I don't mind if my collection is overwritten but I expect that my collections variables, mock server URL and tests are preserved.

[darrencapner]

From watching the recent webinars and reading documentation, there appears to be a workflow in mind, but I find that there is a gap that I have not been able to find a solution for, and would be solved potentially with this issue.

My use case is if I am wanting to iterate on an API design through design, generate collections, deploy, get feedback, and modify design....how would Postman be used if there is no way to update existing collections where test scripts were added for contract testing and performance testing:

One such workflow details:

1. Make an API definition
2. Generate collections for contract testing, performance testing, documentation, working collection, etc.
3. Get feedback to iterate on that API design as new endpoints are added, and changes to existing API contract is changed
4. Generate new collections for contract testing, performance testing, documentation, working collection, etc. keeping all test scripts in those new version collections.

Questions:

1. Do we have to copy tests from existing collections to newly generated collections?
2. Is there a way to generate collections over-top of existing collections, only modifying request contract as per the changes in the API spec?

[a85]

Quick update here: this workflow is top of our minds.

We are looking at flows that allow you to:

1. Update a collection from an existing specification
2. Allow for pull request driven flows in case of conflicts between the new updated collection and the existing collection (so you can review and merge)
3. We are also looking at the reverse flow where you can update a collection and then optionally go backwards and update your specification (in the future, you will be able to do that with a pull request driven flow so you don't overwrite a schema right away)

Unfortunately, at the time being this is a manual process and honestly, we underestimated how popular this would be. Usage is exploding right now for the API tab and we are working hard to fix this loop. We just shipped an integration with GitHub and there is ongoing work with other repositories.

I'd like to thank everyone for their patience and sharing use cases with us. It helps us define the scope quickly and get things to production.

[dpkirchner]

My use case is vastly simpler: I'm writing openapi 3.0 YAML and then I click Generate Collection so I can preview the result to ensure it is correct. I'm not even to the point that I'm writing tests. There is a documentation link in the "Develop" tab and it takes you to a page that looks correct on the surface, however it is missing the API responses. If that page included responses my use case would be satisfied.

[arlemi]

@dpkirchner To display example responses on the documentation you need to add examples in your collection. You can learn how to do that on our Learning Center: https://learning.postman.com/docs/postman/collections/examples/

[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?

[arlemi]

@AmirHmZz This video shows you a step-by-step of updating a collection generated from an API definition: https://www.youtube.com/watch?v=pbkS4XVsUNI

Please make sure you're on the latest version of Postman (v10.12), if not you can download it from here or use Postman in your browser here.

[wooseongshin]

@arlemi
Is this not available in the CLI yet?

[arlemi]

@wooseongshin Having this in the CLI would be a different feature request, I'd recommend opening your own explaining your use-case and what you'd expect the CLI to be doing.

I'll close this issue now that the collection update is available to everyone. 👍

[Andreas-T]

Adding or removing paths does work and triggers a sync notification, as per the video, but changes within an existing path does not. Neither changes in the description, content or response examples are detected.

EDIT: Upon further testing it seems that value changes for existing properties in response examples are detected but new properties are not, even if the schema is updated to reflect the changes.

[sujayvenaik]

but changes within an existing path does not. Neither changes in the description, content or response examples are detected
@Andreas-T can you give one example for this? When you say within an existing path does not: my first hunch is the routes might have wildcards and might be getting matched to some other route. But ill wait for you example to confirm.

--
Upon further testing it seems that value changes for existing properties in response examples are detected but new properties are not, even if the schema is updated to reflect the changes

Can you provide an example if possible?

[GRustamyan-ST]

@wooseongshin Having this in the CLI would be a different feature request, I'd recommend opening your own explaining your use-case and what you'd expect the CLI to be doing.

I'll close this issue now that the collection update is available to everyone. 👍

Does this work for JSON definitions as well?
I tried same API yaml and JSON definition - yaml works, JSON was not working.

[shashankawasthi88]

@GRustamyan-ST it works both for JSON and YAML. Can you share a screen recording of the scenario that is not working for you?

[beckmarc]

I imported my collection via a URL that contains a valid Open API 3 spec in json and yaml format (I tried both). The importing works but when I click on the API to add a collection the "Generate from definition" button is greyed out. Any idea why this happens? I want to sync my API spec with Postman so my frontend devs can easily interact with the API.

[shashankawasthi88]

@beckmarc - can you check for any syntax issues in the spec file that is imported?

[beckmarc01]

@shashankawasthi88 - Yes, I already did using this editor editor.swagger.io. However, in response to your comment I tried out a new one from swagger editor-next.swagger.io and it showed me some new errors. I fixed them and now it works.

[shashankawasthi88]

@beckmarc the Postman schema editor can point out the syntax error as well. Learn more here.

[vladiangelov]

@shashankawasthi88 great work - are there any plans to extend this functionality to GraphQL APIs?

[shashankawasthi88]

@vladiangelov yes we would extend it to GraphQL as well. Do you mind creating a new ticket for it? This one has a lot of different conversations and reopening this will be misleading.

[vladiangelov]

Thanks @shashankawasthi88 - I've followed your advice and created a new issue (as you can see above).

[golkedj]

This was closed but does not add the ability to do this for a collection created from swagger documentation, which seems to be the most requested feature here. Is there a plan for this going foward?

[XedinUnknown]

Yep, I'm doin it. Any progress or plans for this?

[soumyaDarshanee]

Is there a plan to implement updating a postman collection created from Swagger , yet ?

[arlemi]

This is already possible, please follow the instructions in the Learning Center 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

[solo812]

Is the ability to sync a collection available for any other tier than enterprise? Im a solo developer and am looking for this for my personal projects.

[arlemi]

@solo812 This is available for all plans, on the free tier you have the ability to create up to 3 APIs which should be enough for personal projects. 🙂