Skip to main content

Version: 2.13.2304

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:

Postman Create API

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

Postman API Doc


API7.ai Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.

Product

API7 Cloud

SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN PTE. LTD 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation