Allow API refresh when created/imported from an OpenAPI endpoint

[brgrz]

Is your feature request related to a problem? Please describe.

When I'm designing a new API and iterating on it numerous times, I now have to delete and recreate (import again) from my OpenAPI URL to refresh changes. This quickly becomes cumbersome and impractical.

Describe the solution you'd like

If I create an API from an OpenAPI endpoint through the Import URL feature I'd be nice if I had the ability to just click Refresh, obviously with the ability to just overwrite everything that I already have from when I initially added the API.

Describe alternatives you've considered

I didn't really find an option to refresh instantly while work on new API design. Also please note, this is not related to versioning, this is about developer experience before even hitting v1 on an API.

[5thdimensional]

Thank you for your feature request. I'm Steven, a product manager here at Postman, and I'd like to make sure I understand your workflow as well as ask a few questions...

Summarizing My Understanding You have an OpenAPI definition file that you are importing into Postman via the Import > Link feature, and as you are iterating on API designs this flow requires deleting the previously imported API and collections and then re-importing the updated OpenAPI definition from the same URL.

Pain-Point The current behavior is inefficient and adds steps to the process which doesn't provide value, particularly when iterating multiple times on a new API design. Having the ability for changes in the source file to sync over to (or be refreshed within) Postman would eliminate the extra steps that are required for each change.

Follow Up Questions

1. Could you describe what your API design/iteration process looks like, and where does your design/iteration process take place? e.g. are you using an IDE to create the API definition file or are you using another API design tool
2. Is your OpenAPI definition file located in a repo like GitHub?
3. Once the OpenAPI definition has been imported into Postman from the URL, what steps are you then doing in Postman as part of your process? e.g. creating documentation, creating mock servers, API tests, etc.
4. Are there other tools you are using during your design process which are referring back to the same OpenAPI file URL?

[brgrz]

Summarizing My Understanding You have an OpenAPI definition file that you are importing into Postman via the Import > Link feature, and as you are iterating on API designs this flow requires deleting the previously imported API and collections and then re-importing the updated OpenAPI definition from the same URL.

Exactly.

Pain-Point The current behavior is inefficient and adds steps to the process which doesn't provide value, particularly when iterating multiple times on a new API design. Having the ability for changes in the source file to sync over to (or be refreshed within) Postman would eliminate the extra steps that are required for each change.

True.

Wrt to follow up questions: the API design/development happens in IDE, specifically Visual Studio, the OpenAPI document is being generated by Swagger (or other 3rd party tools) and made available through the URL. There's not much more I could say about that. It doesn't matter where this URL points to, be it GitHub or some other host. Most of the time it's just localhost.

[5thdimensional]

@brgrz with our v9 release last September we introduced bi-directional sync of API assets between Postman and source code repos (e.g. GitHub, Gitlab, Bitbucket, etc.). I wanted to touch base to see if you've had an opportunity to explore this feature? This feature addresses some of the challenges you raised when iterating on an API design which then required then having to reimport a file whenever changes were made. It won't address the sync of files from outside a repo (such as a localhost, generic URL, etc.), but I was interested in learning if you've had any success with this new option.

[shashankawasthi88]

@brgrz We have further enhanced the API builder workflow to support a cohesive integration with the repository. Read my blog post to know more. Also, you can schedule a call with me using this link, we can dive deeper into your workflows.

[pwandrag]

@brgrz We have further enhanced the API builder workflow to support a cohesive integration with the repository. Read my blog post to know more. Also, you can schedule a call with me using this link, we can dive deeper into your workflows.

Hi, we build .Net Core api's using CI/CD and have additional libraries that automatically generate swagger files at runtime using reflection, the one we use is Swashbuckle.AspNetCore.SwaggerGen. The feature @brgrz is requesting is a valid usecase in my opinion, our swagger endpoints are always up to date and is not statically hosted on a repository, but rather generated in realtime from code reflection. The url we supply to the import in Postman is the realtime swagger endpoint. A refresh facility to pull in new operations, delete deprecated operations and update existing ones with parameters/payload etc, would be very valuable. In very large organizations that use contract first development methods, you would typically pull a published spec from an api management platform, this spec would also be dynamically generated. The usecases for dynamic swagger updates in my opinion outweigh the static json/yaml pull from repo. I guess you have two paradigms, frameworks who generate code from spec and frameworks that generate spec from code.

[ad-m-ss]

I would like to share that I have a problem with it. Using GitHub sync does not solve the problem.

We use drf-yasg to generate OpenAPI documentation based on a retrospective of our data model, serializers, etc. Thanks to this, the documentation is always consistent with the code running on a given environment, because it was generated from it. There is also no difficulty in determining the version. You know, there's an ongoing discussion in the OpenAPI ecosystem about Code-First vs. Design-First.

I want to use Postman for manual API testing, i.e. Postman as a better REST client.

The solution with creating and deleting collections is not convenient, especially since I have to copy the "Pre-request script" every time, which performs authentication (generating a session token based on login and password for using an API that is not publicly available using classic OAuth flow ).

The solution with GitHub synchronization is also not convenient, because we do not store this documentation in any repository, it is generated live from the code.

The ideal solution would be to re-import the documentation with some clever conflict resolution / overwriting changes - either based on the file (I can download manually, especially since the documentation is not publicly available) or based on the URL. Ideal, and as if this information is stored in Postman so that I can refresh with a single click of a button. I don't know where exactly, possibly as an environment attribute, or maybe a collection.

It needs to refresh, for example, when a new endpoint has been created (e.g. I am evaluating a PR that adds a new API), so I need it to appear in Postman.