We are a SAAS provider so have many clients that all use our base API but have it hosted at custom urls. We want to be able to publish our API documentation at custom URLs with a little custom branding for each client (logo, color and custom url).
Our plan (which so nearly works) was to write one API collection and then create an environment for each client with their base url defined there. Then for publishing documentation we would choose the environment, set the custom domain and color scheme and boom.
This worked great until we realized that you can only publish a collection to one url. Can anyone suggest the best approach to get what we are aiming for? Right now it looks like weād need to create a unique collection for each client but that means maintenance is going to be tricky as weāll need to edit every collection each time our API changes.
You could have a central master collection which you maintain and update.
Next, you could build out a collection that uses Postmanās API. It can retrieve and update collections automatically as well as tell you all the collections in a workspace.
If you created a āclientsā workspace, and duplicated your collection into there for each client and got it setup, come update time you could:
āGet workspaceā on the clients workspace, retrieving a list of all collections within
Hit the āGet collectionā endpoint to retrieve the latest version of the master collection
Hit the āUpdate collectionā endpoint in a loop, providing the response from step 2 as the update to all the collections in the clients workspace.
When the API updates your collection, if the collection is already published then the changes will feed through automatically.
Take a look at building workflows to understand how you can do the looping procedure described in step 3.
Your suggestion is looking promising. I got all the way to step 3 but Iām hitting an error āinstanceFoundErrorā, message āThis collection already exists in the databaseā.
Does this make sense to you? I am making a PUT request to https://api.getpostman.com/collections/{{target_collection_uid}}. I find this error message confusing because I would certainly hope that my collection exists in the database, as thatās what Iām trying to update.
@matt yes the UID is from the duplicated collection (I used the equivalent POST endpoint to create the initial copy.
A GET does retrieve the collection successfully.
One thing I notice, my GET on the master collection is returning null values for the function urls. Perhaps because I am using an environment variable for the urls?
I will try and reduce the complexity of the test by repeating these steps on a dummy collection with one endpoint and see how that goes.
Hi @matt I think I managed to resolve the issues I was facing.
Issue 1 - null values in my urls. I was unaware that I need to āSaveā each method to get the details to properly commit to the postman database. That is why the url was showing up as empty.
Issue 2 - the error āinstanceFoundErrorā, message āThis collection already exists in the databaseā. When I was calling the PUT method, the body of the collection I was sending had some āpostman_idā fields in the lower level pieces of the collection (IDs for the folder and functions). Although the error message implies itās the collection that already exists, I think it really meant āmethods already exist in the databaseā because when I took those id entries out of the post body, the request then went through.
So I think in my script Iām going to have to add a step where I rip out the postman IDs from the various layers so that it doesnāt run into any conflicts.
Oh, and I actually also had to go and delete the āidā values of all the other things like examples, tests and pre-requests. Just in case this helps anyone else in the future.