Publishing Documentation to Custom Urls for each Environment


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.

Thanks for any help!

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:

  1. ‘Get workspace’ on the clients workspace, retrieving a list of all collections within
  2. Hit the ‘Get collection’ endpoint to retrieve the latest version of the master collection
  3. 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.

Thanks for the suggestion. I’ll play around with the API and see if I can get it working as you suggest.

Hi @matt

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{{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.

Any ideas? Thanks!

1 Like

Is the collection_uid you’re using reflective of the UID for one of the replicated/client collections? Where did you retrieve the UID from?

If you try a GET on the same endpoint, does it retrieve the client/replicated collection successfully?

@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.

Yeah give that a try and see how you get on… else might need to see a sample request body or something to make more sense of it.

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.