Postman 🔌

Terms
Developing an API
Consuming an API

The team uses Postman for managing and sharing APIs. It streamlines the development process, creates a single source of truth for a project’s APIs, and enhances collaboration across the development and product teams.

Terms

A Workspace is a container of all the Postman things a team come to use: collections, environments, mocks, monitors, and more. Each project must have a dedicated team workspace. When developing or consuming an API, selecting the right project workspace will filter the APIs for that project only.
A Collection is a group of all APIs developed by a party, either Nimble or a third party. As long as they belong to the same project, the team prefers to have all of those API collections under the same project workspace. Each collection can have multiple folders to group related APIs.
A Variable, as the name implies, allows to store and reuse values in requests and can be referenced throughout collections, environments, and requests.
An Environment is a set of variables to use in the Postman requests. Some typical environments: nightly, staging, production.
An Example is a recorded, tightly coupled request and response pair.

Developing an API

The way the team develops an API and documents it on Postman is quite similar to the way the team uses Git in some ways.

Naming

As a general rule, use a concise and descriptive phrase to name the element and always capitalize on the first character of each word.

Collection: name it using proper title casing.
```
Acme API
```
Variable: use snake casing.
```
access_token
user_email
```
Environment: name it in this form collection name - environment name.
```
Acme API - Production
Stripe - Staging
```
API request: start naming it with a verb in the present tense, so there’s a clear expectation of what action the request does.
```
Create Account
Verify Password
```
Example: name it in this form HTTP status code - short description for the response.
```
200 - Transfer Success
422 - User Already Exists
404 - User Not Found
```

Using Collections

By default, there must be a default collection that is read-only for all developers.
When developing a new API, a new collection must be forked from the main collection to document the new API.
The forked collection label must be hyphenated and prefixed with the user story ID.
```
acme-133-user-register-new-account
acme-177-user-reset-password
```

If the API supports multiple versions, it must be namespaced under the collection.

Acme API
├── V1
│   └── Account
└── V2
    └── Account

Documenting a New API

Group all related APIs under the same folder. e.g. Account folder contains all of the APIs related to the user account.
Each API endpoint must have at least an example of a successful response and an example of a failed response – if it exists.

Prefer to set all parameter values in the header, path & query string which can change the API response as variables.

# variable as path parameter
/users/{{user_id}}

# variable as header value
Authorization: {{user_token_type}} {{user_access_token}}

# variable as body parameter
{
  "username": {{username}}
  "password": {{password}}
}

Using Postman’s endpoint description to document the request, the more detailed the better but at least, the following information must be provided:

A request description to describe what it does in more detail because the request name is usually concise and sometimes isn’t descriptive enough. It is also the place to explain how to use the API, especially in case several APIs must be used sequentially to achieve a goal.

- Request name: `Request Account Recovery`.
- Request description:
  Start the account recovery process to get the request ID. Next steps are:
  - Using the `Select Verification Methods` API to choose mobile phone number or email as verification method.
  - Using the `Verify OTP` API to verify the OTP code.

Each parameter & header must also have a description.

Parameter name: `code`
Parameter description: The otp code received by email or mobile number.

Header name: `Accept-Language`
Header description: The expected language for the response. Either 'en' or 'th' is accepted.

Prefer to use tests to set the variables whenever possible as it allows to use a collection “click and play” where variables are automatically passed from one endpoint to the next.

# Request ID returned by the `Request Account Recovery` API if automatically set
{{acme-api-domain}}/account_recovery

# Becomes the parameter for the `Select Verification Method` API
{{acme-api-domain}}/account-recovery/{{request_id}}

Opening a Pull Request

Once the API development is completed and it is ready to be merged to the main collection, a pull request must be submitted for review.

The name of the pull request must contain both the user story ID and title:
```
[<User Story ID>] As a user I can view the list of exclusive rewards
```
If the Git pull request of the API hasn’t been merged and deployed, the Postman pull request name must be prepended with the prefix [WIP] so the Postman pull request reviewers know it is not ready to review and test yet.
```
[WIP][<User Story ID>] As a user I can view the list of exclusive rewards
```
The description of the pull request must abide by this template. It is similar to the Git pull request template the team uses:
- On the first line, include the link(s) to the user story(ies) to make it easier for reviewers to get the complete requirements
```
# Shorcut
https://app.shortcut.com/nimble-website/story/23792

# JIRA
https://nimblehq.atlassian.net/browse/BRAIV-18
```
- What Happened: provide a description of the changes made. If there are some pending TODOs, include them there as well.
- Insight: any guidance for reviewers to better understand the changes.
Between one to two reviewers must be added to each pull request.

Reviewing a Pull Request

Reviewers look for the pull requests which are ready for review - those not in draft or without the [WIP] prefix.
Reviewers approve the pull request when it passes the team guidelines and solves the issue at hand in a satisfying way.
Reviewers must test it on a non-local environment, e.g. staging to verify.
Merge once confident in the API documentation and carefully tested it.

Consuming an API

Select the right workspace for the project.
Choose the right API collection.
Browse for the expected API.
Go through the examples of the API to see the requests and responses if running an actual API request is unnecessary.
Otherwise, choose the expected environment to run the API request.
Input the values for the variables if necessary and hit Send to get the response.