Designing APIs

As engineers, we always emphasize the importance of designing a plan before coding.We need to clarify the functional purpose of an API based on the business requirements and then translate the business language into technical language. Typically, API planning and design revolve around documentation.

This article will guide you in designing multiple APIs and creating comprehensive API documentation.

API Samples

In this comprehensive guide on API lifecycle management, we will utilize an example of an e-shop that encompasses two fundamental concepts:

Product: Includes information such as ID, name, and price.

Order: Includes the product ID, customer ID (in this example, we will not elaborate on the concept of customers), and the quantity of the product.

Based on these two core concepts, we will design the following three APIs:

GetProductById

Request:

 '${baseUrl}/products/1' 

Response:

{
    "id": 1,
    "name": "iPhone 13 Pro",
    "price": 999.99,
    "updated_at": "2023-04-17T05:49:54.029Z",
    "created_at": "2023-04-17T05:49:54.029Z"
}

CreateProduct

Request:

curl '${baseUrl}/products' \
-X POST
--data '{
  "name": "iPhone 13 Pro",
  "price": 999.99
}'

Response:

{
  "id": 1
}

CreateOrder

Request:

curl '${baseUrl}/orders' \
-X POST \
--data '{
    "customer_id":"user_ascx8e21nsd", 
    "product_id": 1,
    "quantity": 1
}'

Response:

{
  "order_id": 123
}

Background

Postman

We will be using Postman to demonstrate API design. Make sure you have Postman ready.

RESTful API

The key characteristics of the RESTful architectural style include:

• Unique identification of resources: Each resource has a unique identifier, such as a URL.
• Uniform interface: Utilizing standardized HTTP methods and status codes, such as GET, POST, PUT, DELETE, etc.
• Stateless: APIs should not store client state information. Each request should contain all the necessary information for processing, facilitating horizontal scalability.

Designing API Definition Document

We can use the schema approach to write API definition files that adhere to the RESTful architectural style and API design principles. These files can be described and communicated in JSON or YAML format. This approach ensures the reliability, consistency, and scalability of the API, while also facilitating documentation writing and integration with other platforms.

There are several open-source tools available for editing OpenAPI specification files, such as Swagger Editor and OpenAPI GUI. These tools provide interfaces and utilities for creating, editing, and validating APIs that comply with the specification. Additionally, many IDEs or editors, such as Visual Studio Code and IntelliJ IDEA, have corresponding OpenAPI plugins.

Here is an example API documentation file for a shopping service, shop.yaml, which includes three APIs:

---
openapi: 3.0.0
info:
  title: Sample API
  description: A sample API for demonstration purposes
  version: 1.0.0
servers:
- url: http://localhost:9080
  description: Development server
paths:
  "/products/{id}":
    get:
      summary: Get product by ID
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the product
        schema:
          type: integer
      responses:
        '200':
          description: Product data
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  price:
                    type: number
                    format: float
                  updated_at:
                    type: string
                    format: date-time
                  created_at:
                    type: string
                    format: date-time
                example:
                  id: 1
                  name: iPhone 13 Pro
                  price: 999.99
                  updated_at: '2023-04-17T05:49:54.029Z'
                  created_at: '2023-04-17T05:49:54.029Z'
  "/products":
    post:
      summary: Create product
      requestBody:
        required: true
        description: Product data
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                price:
                  type: number
                  format: float
              required:
              - name
              - price
              example:
                name: iPhone 13 Pro
                price: 999.99
      responses:
        '201':
          description: Product created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                example:
                  id: 1
  "/orders":
    post:
      summary: Create order
      requestBody:
        required: true
        description: Order data
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                product_id:
                  type: integer
                quantity:
                  type: integer
                  minimum: 1
              required:
              - customer_id
              - product_id
              - quantity
              example:
                customer_id: user_ascx8e21nsd
                product_id: 1
                quantity: 1
      responses:
        '201':
          description: Order created

Create APIs in Postman

Once you have logged in to Postman, create or select an existing Workspace. Then, within that workspace, create an API named shop, then add the definition file to the API:

Select the Import files option and import the prepared API documentation file shop.yaml: