API 🔌

Hero image for API 🔌

Tool

We use 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 you’ve come to use: collections, environments, mocks, monitors, and more. Each project must have a dedicated team workspace. Either you are 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, we prefer 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 you can use in your Postman requests. Some typical environments: nightly, staging, production.
  • An Example is a recorded, tightly coupled request and response pair.

Developing an API

The way we develop an API and document it on Postman is quite similar to the way we use Git in some ways.

Naming

As a general rule, using 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.
  • 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 fail response - if it exists.
  • Prefer to set all parameters 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 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 isn’t 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’s similar to the Git pull request template we are using:
    • On the first line, include the link(s) to the user story(ies) to make it easier for reviewers to get the complete requirements

      # Pivotal Tracker
      https://www.pivotaltracker.com/story/show/133252875
          
      # 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 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 you feel confident in the API documentation and carefully tested it.

Consuming an API

  • Select the right workspace for the project.
  • Chose the right API collection.
  • Browse for the API you want to use.
  • Go through the examples of the API to see the requests and responses if you don’t need to run a real API request.
  • Otherwise, chose the environment you want to run the API request.
  • Input the values for the variables if necessary and hit Send to get the response.