We are just getting started with documenting and testing our API. We decided to rely heavily on Postman, but so far I am not happy with the development workflow. I’m sure I’m doing something that can be simplified, so please let me know what that is.
We keep Postman tests in Git, exported as JSON. We import this into the Postman GUI to work on it.
For a new service, we create a spec in Swagger/OpenAPI 3. We decided to use this documentation standard because it offers interoperability with various other technologies.
We import the spec into Postman. This doesn’t really buy us more than a starting point for Postman tests.
We add the imported/new tests to our existing Postman collection through the Postman GUI.
We work on the tests as needed.
We export from the Postman GUI back to the JSON document, which is tracked in Git. This is not straight-forward, since the GUI seems to touch a lot more than just the tests that were added or edited.
I think your workflow is as good as it can get. Basically you have two options:
Export / import collections as files (your current scenario) which is a good option if your team is small and you only do changes in a coordinated fashion. You have the overhead pulling / importing / exporting / committing but it is free and you always have a backup in your repository. It is really suboptimal if you want to do code-reviews or run into merge conflicts.
You will always have some side-effects such as changed internal ids what Postman uses but apart from this you should not have any other issues.
Use Team workspaces which for a small number of requests it should be free (good for evaluating) but for normal use-cases you need to pay.
You rely on the Postman servers for storing and syncing everything but can also create backups if you want.
Using team workspaces excludes the usage of Git, even if you have some Git similar features, you cannot do diffs to see who has changed what (unless you fork and merge and do a review at this step).
Hey @andrew1, I think if you used Git Hooks in conjunction with Postman’s API you could remove some of the manual process. There’s a basic example in the following article:
Hey @matt thank you for your blog post and interesting idea you bring to this discussion.
While your solution is as geeky as it gets, I do have some concerns when it comes to its implementation when it comes to the day-to-day use of Postman (no offense intended).
I think it would be a nice addition to automatically delete the existing collection before importing a new one. Especially for large collections, you end up with multiple collections with the same name and it is hard to know which one is which (if you don’t manually delete them first).
It also looks like when using the Postman API, the JSON file is no longer “pretty” and this makes looking at the history or pull request a pain.
I think power users can get some benefits from implementing this but it may be just too much overhead for “normal” users.
Overall working with Git from Postman remains hard and I guess everybody would really like a better solution.
@vdespa - absolutely agree and have a bit of commentary for you on the points you raised.
I think it would be a nice addition to automatically delete the existing collection before importing a new one. Especially for large collections, you end up with multiple collections with the same name and it is hard to know which one is which (if you don’t manually delete them first).
For sure, you can even see on this line I was considering the same thing. Ultimately, these hooks were intended to be as basic of an example as I could create as there wouldn’t be a one size fits all solution here - not everyone works with git in the same way. I’d take these as an idea to what’s possible and something you can really go as far as you want on.
It also looks like when using the Postman API, the JSON file is no longer “pretty” and this makes looking at the history or pull request a pain.
Agree - it’s definitely possible to fix this but not something I did in these initial examples. I may revisit and make such tweaks if it doesn’t add too much weight to these hooks as a basic starting point!
I think power users can get some benefits from implementing this but it may be just too much overhead for “normal” users.
Indeed, this is really going to be for those who are desperate to have a more automated git based workflow and serves as a method for getting this done prior to a deeper git integration within Postman itself.
Overall working with Git from Postman remains hard and I guess everybody would really like a better solution.
- we’re putting a lot of thought into this