API governance commands

This topic covers API governance commands for the Postman CLI.

API governance is the practice of applying a defined set of standards consistently across the API design and testing phases of your development process. The Postman CLI includes commands that checks your API specifications in Spec Hub against your team’s configured Postman API governance rules.

`postman spec lint`

This command runs syntax validation and governance rule checks against a single- or multi-file API specification in Spec Hub. Provide the local file path or ID for a specification that’s in OpenAPI 2.0, 3.0, or 3.1 format. If you’re providing the local file path for a multi-file specification, provide the path to the root file.

By default, if you provide a local file path for a specification, the command runs syntax validation and governance checks using the All workspaces governance group. Use the --workspace-id option to run governance checks using the rules from a specific workspace.

To use this command, sign in to Postman with the postman login command.

You can find the specification ID in Postman. Click Items tab, click Specs in the sidebar, and select a specification. Then click the Specification Info tab in the right sidebar to view or copy the specification ID.

Usage

$ postman spec lint <spec-file-path|spec-id> [options]

<spec-file-path|spec-id>

The local file path to the API specification or the specification’s unique identifier.

Options

--fail-severity [severity], -f

Defaults to ERROR

Triggers an exit failure code for rule violations at or higher than the specified severity level. The options, in order of lowest to highest severity, are HINT, INFO, WARNING, and ERROR.

--output [output-format], -o

Controls the output format for issues found in the OpenAPI specification. Accepts JSON or CSV. Defaults to table view if no output format is specified.

--workspace-id [workspace-id]

Run syntax validation and governance rule checks using the rules from a particular workspace by providing its ID. You can use this option if you provide the local file path for a specification. Learn how to get a workspace’s ID.

Examples

$ postman spec lint openapi.yaml --workspace-id 987654321-54321ef-4321-1ab2-1ab2-ab1234112a12
$ postman spec lint 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Learn more at API governance overview and Use the Postman CLI with GitHub Actions.

Output

You can change the output of governance rule violations to JSON or CSV. If you don’t specify an output, it defaults to table view.

The following is an example of the output in table format (default):

Example output

The following is an example of the output in JSON format:

1 {
2   "violations": [
3     {
4       "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
5       "line number": "13",
6       "path": "paths./spacecrafts/{spacecraftIds}.parameters.0",
7       "severity": "WARNING",
8       "issue": "Parameter \"spacecraftId\" must be used in path \"/spacecrafts/{spacecraftIds}\".",
9       "issue type": "Syntax"
10     },
11     {
12       "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
13       "line number": "19",
14       "path": "paths./spacecrafts/{spacecraftIds}.get",
15       "severity": "WARNING",
16       "issue": "Operation must define parameter \"{spacecraftIds}\" as expected by path \"/spacecrafts/{spacecraftIds}\".",
17       "issue type": "Syntax"
18     },
19     {
20       "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
21       "line number": "4",
22       "path": "info",
23       "severity": "WARNING",
24       "issue": "The info object should have a description.",
25       "issue type": "Governance"
26     },
27     {
28       "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
29       "line number": "21",
30       "path": "paths./spacecrafts/{spacecraftIds}.get.responses",
31       "severity": "WARNING",
32       "issue": "Operation should return a 5xx HTTP status code",
33       "issue type": "Governance"
34     }
35   ]
36 }

The following is an example of the output in CSV format:

1 file,line number,path,severity,issue,issue type
2 ../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,13,paths./spacecrafts/{spacecraftIds}.parameters.0,WARNING,"Parameter ""spacecraftId"" must be used in path ""/spacecrafts/{spacecraftIds}"".",Syntax
3 ../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,19,paths./spacecrafts/{spacecraftIds}.get,WARNING,"Operation must define parameter ""{spacecraftIds}"" as expected by path ""/spacecrafts/{spacecraftIds}"".",Syntax
4 ../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,4,info,WARNING,The info object should have a description.,Governance
5 ../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,21,paths./spacecrafts/{spacecraftIds}.get.responses,WARNING,Operation should return a 5xx HTTP status code,Governance

`postman api lint`

The postman api lint command is only supported for API Builder objects in Postman v11. The Postman API Builder isn’t supported in Postman v12 and later. Learn about using the API Builder in Postman v11 and earlier.

This command runs validation checks for governance rules against the API specification provided in the Postman config file, a local file, or a UUID. The api lint command shows a warning if it’s unable to find the API ID to send data back to Postman.

This command supports APIs in the Postman API Builder that aren’t linked to Git.

To use this command, sign in to Postman with the postman login command.

Usage

$ postman api lint <definition-file|api-uuid> [options]

<definition-file|api-uuid>

The API definition file path or API UUID to lint.

Options

--fail-severity [severity], -f

Defaults to ERROR

Triggers an exit failure code for rule violations at or higher than the specified severity level. The options, in order of lowest to highest severity, are HINT, INFO, WARN, and ERROR.

--suppress-exit-code, -x

Specifies whether to override the default exit code for the current run.

Examples

$ postman api lint my-definition-file.json
$ postman api lint 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Learn more at API governance overview.