Skip to content

Document support for postman environment file

Herber Madrigal requested to merge 356312-document-support-for-postman-environment-file into master

What does this MR do?

API Security scanner consumes API spec documents. There are many API spec formats and one of them is Postman Collection. Postman is a graphic tool and can produce different files other than the Postman Collection. API Security was only able to consume the Postman Collection and a custom format (that due to lack of a better name I refer to it as flat JSON object ). The custom format provides a set of values for variables. These values are consumed by the scanner when processing the Postman Collection.

This MR allows customers to use an alternative file format to provide values for variables. This new supported format is Postman environment. Previously only the custom format (flat JSON object) was supported.

Also, variables have a hierarchy, in order to compute their value. This MR documents the support to two more types of variables in the hierarchy: Global and Environmental. These type variables can be loaded from the Postman environment format. Previously, only two types of variables were available: Collection variables loaded from Postman Collection and variables from the flat JSON object.

This MR also documents an update in variable _POSTMAN_COLLECTION_VARIABLES. In order to provide Global and Environmental variables which can be in different files, the variable _POSTMAN_COLLECTION_VARIABLES has been changed to accept a list of files (comma separated values), previously only one file could be set in _POSTMAN_COLLECTION_VARIABLES

The last documented change is about how to handle undefined variables. In this case, API Security follows the same behavior as Postman runner, it keeps the text of the variable reference the same without any text substitution.

This MR focuses on documenting:

  • Add support to a new file format to replace the custom format (a flat JSON object). This new format is called Postman Environment.
  • An update in the Postman variable section to explain how to edit and create the postman environment file.
  • The postman environment file introduces an existing concept in postman called variable scope. Pretty much, a variable can be defined as a value in different locations. The variable scope defines the rules to select a value in a given context. This MR mentions the existing support for the Collection scope and points out the new supported Scopes: Global and Environment.
  • Explains default behavior when the variable is undefined.

Related issues

Author's checklist

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like `Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.
Edited by Herber Madrigal

Merge request reports