Hi,
I have some existing documentation for our Service API which is at a collection level and is published to a custom URL.
However, we are now expanding the API and it includes a webhook definition for event notification that clients of our API should implement.
I want to document and publish these as two separate collections and have documentation at three levels
Workspace for Introduction, common concepts etc
Service API collection for the APIs that we expose for clients to call
Webhook collection for the details of the webhook that clients should expose
I assumed that I could change the level at which the publishing to the custom URL is done from a collection within the workspace to the workspace. Unfortunately, I do not seem to be able to do so, or at least I cannot find a way of doing so.
Is it possible? And if so how?
If it is not possible, what is the recommended way of documenting these two intrinsically linked but distinct collections. Do I need to create three collections with one being just for common documentation and then publish all and cross reference them? It seems laborious, but is this the only way?
I’m not fully aware of your context but are you in the position to create a Public Workspace where those Collections (With their documentation) could live? You could also create a top level Workspace documentation for that too as well as other benefits.
For example, we have the Postman API documentation in a Public Workspace, as well as other Collections, where our users can directly access those endpoints and read the documentation for each of them.
HI Danny,
Thanks for taking the time to respond. That is what I have done but so far but it is not fully what I need.
Currently I have a public API and it is documented as a single collection in a workspace on a custom url. Lets say it is accessible at myapi.example.com.
I am now added a second collection in the same workspace, it is not yet published and I have new documentation that I also want to publish at the workspace level. I would now like to make all the documentation available at a single custom URL say mynewapi.example.com. While we have previously published to a custom url at a collection level I cannot see how that is done at the workspace level so that all documentation at both the workspace and collections are accessible.
I hope that makes sense.
A whole Workspace can be made publically visible for everyone to see, like in the link I shared to Postman’s Public Workspace. Within that Public Workspace, we have several different individual Collections.
That workspace link can then be shared with anyone. Like the one here:
You can create copies of your Collections and fork them into the Public Workspace if you want/need to make changes to the main Collection before sharing with your client/users. They can fork those Collections into their own Workspaces and have a working copy so that they get start using your endpoints, etc.
Hi Danny,
I understand and I have that already. It is the use of a custom url that has me stumped. I do not want a www.postman.com domain, rather we want to our own domain as we currently have configured in postman for the single collection.
Perhaps I should tweak the title a little to make it clearer.
I fully understand what you’re trying to do but it’s not possible to do that without either making a Public Workspace and placing those Collections inside it or the same way you’re doing it now by publishing single Collections.
There isn’t a Publish Workspace button in the same way as a Collection. That would be where those Public Workspaces come in or even Partner Workspaces depending on the licence type.
,