API Specification Design Guide with Stoplight.io and Postman

February 24, 2024 (4mo ago)


Welcome to the API Specification Design Guide for developers. This document aims to provide you with a comprehensive guide on designing API specifications using popular design tools like Stoplight.io and Postman. Whether you are a seasoned developer or just getting started with API development, this guide will walk you through the process of creating a well-structured API specification.

1. Getting Access to Stoplight.io and Postman


Stoplight.io offers a user-friendly API design and documentation platform. To get started:

  1. Visit Stoplight.io and sign up for an account.
  2. Once registered, log in to your account.
  3. Explore the available features and create a new project to begin designing your API.


Postman is a powerful API development and testing tool. Follow these steps:

  1. Visit Postman and sign up for an account.
  2. After signing up, log in to your Postman account.
  3. Download and install the Postman app on your machine.

2. Stoplight.io Tutorial

2.1 Creating a New Project

In Stoplight.io:

  1. Click on the purple plus button or "Create New" within the Projects tab to start a new project.
  2. Choose the appropriate template (e.g., OpenAPI, GraphQL). We will mainly be using OpenAPI specs.
  3. Name your project.

2.2 Designing Endpoints

  1. Navigate to the "Design" tab.
  2. Add new paths and define operations for each endpoint.
  3. Use the intuitive visual editor to specify request and response details.

2.3 Collaboration and Version Control

  1. Invite team members to collaborate on your project. This may be a paid feature, we do not currently have a license for Stoplight.io.
  2. Utilize version control features to track changes and manage different versions of your API.

2.4 Sharing the specification to non-collaborators

  1. Use the 'Publish' function within the project to save your changes and push them to the sharable URL.
  2. Copy the published URL and add to the ticket for PR.

3. Understanding YAML OpenAPI Specification

Stoplight gives you access to edit the YML/JSON definition for your API specification directly for more fine control. This is done using the 'Code' button on the top right of the design interface for each endpoint.

The following is a basic overview of how this specification is laid out.

Hot tip #1 You can visit any of our existing SwaggerDoc pages for our APIs and download the 'swagger.json' file using the link at the top - this is an API specification you could use as a starting point within Stoplight or Postman.

A quick way of switching from JSON to YML if you prefer it is by importing it to Stoplight under a new project, then in the Files tab on the left locate the JSON file, right click and export as YML format.

Hot tip #2 If you find you are more comfortable using the specification definition directly to design your API then there are tools available in VS Code to publish these files to web-based documentation directly. These tools don't provide a GUI for design at all, you just have the JSON/YML spec.

This extension requires a free Redocly account, and API Key - instructions are provided on first usage in VSCode: Redocly OpenAPI Editor VSCode Extension

This extension runs without the need for an account or API key, but it isn't as stable: 42Crunch OpenAPI Editor VSCode Extension

3.1 Basic Structure

openapi: 3.0.0
  title: Your API Title
  version: 1.0.0

3.2 Defining Paths and Operations

      summary: Get a list of users
          description: Successful response

3.3 Adding Parameters and Request/Response Examples

      summary: Get user by ID
        - name: id
          in: path
          required: true
          description: Successful response
                id: 123
                name: John Doe

3.4 Reusable Components and References

      type: object
          type: integer
          type: string

4. Postman for API Design

4.1 Creating Collections

  1. Open Postman and click "New" to create a collection.
  2. Define the collection's name and description.
  3. Add requests to the collection, specifying method, URL, headers, and body.

4.2 Designing Requests

  1. Configure request details such as method, URL, headers, and parameters.
  2. Utilize the visual editor to structure request body content.

4.3 Collaboration with Postman

  1. Share your Postman collection with team members for collaborative development and testing.
  2. Use Postman workspaces to organize and manage your API projects.

4.4 Publishing your Design

  1. In the workspace side bar on the left side locate your new collection.
  2. Use the context menu (three dots button) to 'View Documentation'
  3. Review the generated documentation and ensure you don't need to make any tweaks.
  4. When you are happy click the Publish button in the top right - this will open your browser.
  5. Complete the form and click publish.
  6. Copy the shown 'URL for published documentation' and post into the ticket for peer review.

4.4 Testing and Mocking - Additional Functionality

  1. Write test scripts to validate API responses.
  2. Use Postman's mocking feature to simulate API responses for testing purposes.

5. Best Practices

5.1 Consistency and Naming

  • Maintain consistent naming conventions for paths, parameters, and schemas.
  • Use clear and descriptive names for endpoints and operations.

5.2 Documentation

  • Document each endpoint, parameter, and response to provide clear guidance for users. This could be the form of detailed descriptions added to your yaml spec.
  • Utilize tools like Stoplight.io or Postman for automated documentation generation.

5.3 Security Considerations

  • Implement appropriate security measures, such as API keys or OAuth, as per your application requirements. We should always include these on our APIs, so details about the OAuth 2.0 setup and token URL should be in the specification.
  • Clearly document security considerations in your API documentation.

By following this guide, you'll be well-equipped to design robust API specifications using popular tools like Stoplight.io and Postman. Remember to adhere to best practices and continuously iterate on your designs based on feedback and evolving requirements. Happy designing!