postman

Postman does not respect my publication environment for the target url in code samples


I am publishing my documentation with NO environment. My documentation will be useful to partners to whom we've provided the URL for our API endpoints, access tokens, etc. Without this supplementary information, the general public can view the documentation, but not access the API since they won't have a valid access token. Indeed I don't want them to even have the URL to our API because I don't want to encourage bad actors to bang away at our API even without a valid token.

But here's how this is published. On the left, you can see that Postman is omitting the value substitution for all tokens, because the documentation is published with no environment. On the right however, within the code sample, token substitution is omitted for the headers, however for the target endpoint the value of the URL is merged in, despite the fact that I've published this without any environment.

Am I setting this up improperly for publication or is this a bug in the Postman publication feature? If the latter, is there a workaround for this? Thanks for your advice!

Postman Publication


Solution

  • Actually, the bug is not in the publication process, the bug is in the "Save Response" feature, when you prepare samples of your calls for publication. Have a look:

    Here is what my response looks like:

    Note that the headers and the base url are nicely tokenized.

    Postman Initial Response

    After a save the response though, here's what the saved response looks like:

    Note that the headers are still nicely tokenized, but for some reason the URL is no longer tokenized, rather it is fully resolved to the value of the environment variable. Thus, when generating the documentation, the URL shows up in the code samples.

    Postman Saved Response

    The workaround to this issue is that the saved response must be edited to restore the token {{whatever}} into the url so that the resolved url is not exposed when the documentation is published. I tried this and it works.

    Edit: As I'm working with the Postman documentation feature, I'm finding that the Save Response feature is problematic in this respect in many areas. I can't pin it down, but sometimes it replaces variable references with their literal values and sometimes it leaves the variable references in place. What I have found is that I need to go through my saved responses manually before I publish and restore the variable references so that they show up as such in the published documentation. Actually, when I restore these references, I need to code an "artificial syntax", that is {reference} rather than {{reference}} because if I do the latter I will revisit the response at a later point and find that Postman has reverted the variable reference back to its literal contents.

    If someone from Postman sees this - can you please correct your Save Response feature (or at least provide an option) so that it preserves variable references from the original request. Thank you.