12 points to note when sharing interface design documents-PHP Tutorial-php.cn

Preface

We do back-end development, and we often need to define interface documents.

When I was doing interface document review recently, I found that the parameter defined by a small partner was an enumeration value, but the interface document did not provide the corresponding Specific enumeration value . In fact, how to write interface documents well is really important. Today, Brother Tianluo brings you 12 points to note in interface design documents~

12 points to note when sharing interface design documents

Public account: Little boy picking up snails (There is a carefully original interview PDF of snails)
github address, thank you for every star: github

1. Are your interface names clear?

In other words, what does your interface do and is it easy to understand and clear? The general interfaceurl also requires that the function of the interface can be seen. For example, Query User Information (queryUserInfo) is a good interface name.

12 points to note when sharing interface design documents

2. Is your interface address complete?

The address of the interface is also called the URL address of the interface. That is, what URL is used when others call your interface. For example, /api/user/queryUserInfo is an interface address. However, what I want to say is that this is not a complete interface address. Is your interface called HTTP?

If HTTP is called, what is the domain name? Port. A good http interface address should be like this:

https//tianluo.com:15000/api/user/queryUserInfo

12 points to note when sharing interface design documents

3. Is your interface request method correct?

Interface request methods usually include the following:

GET: To obtain resources from the server, you can pass parameters in URL, which is usually used to query data.
POST: Submit data to the server, usually used for operations such as adding, modifying, and deleting.
PUT: Update resources to the server, usually used to update data.
DELETE: Delete resources from the server, usually used to delete data.
PATCH: Partially updates resources to the server, usually used to modify some data.
HEAD: Similar to the GET request, but only returns the response header and not the entity content. It is usually used to obtain meta-information of resources.
OPTIONS: Request the server to return supported request methods and other information, usually used for the client and server to negotiate the request method.

When you define the interface document, you need to write clearly, which is your interface request method? Under normal circumstances, we use POST and GET more often. There are also companies that use POST for all interfaces.

12 points to note when sharing interface design documents

4. 8 major elements of request parameters

When we define the interface, the request parameters are one of the most important parts . For a qualified interface document, the request parameters should contain these eight elements:

Parameter name: The name of the parameter is named in camel case, such as userId.
Type: The type of parameter, such as String, Integer, etc.
Required: Whether the request parameters are required. If required, when the upstream does not pass this parameter, a parameter verification exception should be thrown.
Default value: If this parameter is not passed, is there a default value and what is the default value.
Value range: If it is a numerical type such as Long, Integer, this is a range value, such as 1~10, if it is an enumeration value, That is the enumeration range, such as ACTIVE, INACTIVE.
Parameter format: For example, if your parameter is a date, you need to specify the parameter format, such as yyyyMMdd
Input parameter example value: Provide an example value of the response parameter, So that developers can better understand and use this parameter.
Remarks: If there are special instructions for this input parameter field, you can explain it in this column. If there is no special explanation, it is okay to just describe the function of this parameter.

The following is a sample document for entering parameters:

Parameter name	Type	Required or not	Default value	Value range	Parameter format	Input parameter example value	Remarks (description)
userId	Long	is	0L	0~99999999L	None	666L	UserId
birthDay	String	is	19900101	19900101~20231231	yyyyMMdd	19940107	User birthday

12 points to note when sharing interface design documents

##5. 7 major requirements for response parameters

Response Parameters are actually similar to input parameters. There are 7 elements:

Parameter type: describes the data type of the response parameter, such as
String, Integer, etc.
yyyy-MM-dd, HH:mm:ss, etc.
Value range: Describes the value range of the response parameter, such as
integer range, string length, etc.
Example value: Provide an example value for this response parameter so that developers can better understand and use this parameter.

The difference is that the response parameters are generally returned in the format of

code, msg, data:

{
    "code": 0,
    "message": "success",
    "data": {
        "name": "Tom",
        "age": 20,
        "gender": "男"
    }
}

Copy after login

6. Interface error code

A good interface document must include error code enumeration. The general error code definition includes three columns:

Error code, error code information, meaning

##Error code##1001Parameter errorIllegal request parameter1002The user does not existThe corresponding user information was not found based on the given user ID Database error

Error information Meaning

##1003

Database access error

12 points to note when sharing interface design documents

7.接口安全

定义接口文档时，对于一些需要保护的接口，也需要考虑接口的安全，例如权限管理、防止 SQL 注入等。

因此，接口文档应当包含接口的安全性说明：例如接口的访问授权方式、数据传输加密方式等。此外，接口文档还应该对于敏感数据和操作进行标注，方便使用者注意隐私和安全问题。

12 points to note when sharing interface design documents

8. 接口版本管理

在接口文档定义时，接口版本管理是非常重要的一个方面。由于软件项目的迭代和升级，接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰，需要对接口进行版本管理。

以下是一些常用的接口版本管理方法：

在接口文档中明确版本号：在接口文档中明确标识接口的版本号，例如在接口地址中添加版本号信息，如https://example.com/api/v1/user，表示该接口的版本号为v1。
使用语义化版本号：采用语义化版本号（Semantic Versioning）规范，即版本号格式为X.Y.Z，其中X表示主版本号、Y表示次版本号、Z表示修订号。当进行兼容性变更时，需升级主版本号；当增加功能且不影响现有功能时，需升级次版本号；当进行bug修复或小功能改进时，需升级修订号。
增量发布：在接口发生变化时，先发布新版本的接口，同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口，最终可以将旧版本的接口废弃。

无论采用何种方法，接口版本管理都应该得到充分的考虑。在接口版本变化时，需要及时更新接口文档（详细描述版本的变化、兼容性问题、版本切换方式等），以确保用户能够获得最新的接口信息。

9. 维护接口文档更新迭代

如果接口发生了变更，比如参数有哪些变更，错误码变更等等，都需要维护到文档上。同时需要登记变更的记录。

日期	变更描述	操作人
2023-04-16	创建接口文档，定义了第一版接口文档	捡田螺的小男孩
2023-04-18	修改接口文档，增加了错误码，出参等	田螺哥

12 points to note when sharing interface design documents

10.明确请求头有哪些

接口文档，是需要写清楚的请求头的。接口文档的请求头可以看到以下的信息：

Content-Type：指定请求体的数据格式，如application/json、application/x-www-form-urlencoded、multipart/form-data等。
Authorization：用于身份验证的令牌信息，如Token、Bearer等。
Accept：指定客户端可以接受的响应数据格式，如application/json、text/html等。
User-Agent：指定客户端的类型和版本信息，可以用于服务端进行针对性优化。
Accept-Encoding：指定客户端可以接受的数据压缩格式，如gzip、deflate等。
Cache-Control：指定客户端缓存的策略，如no-cache、max-age等。
Cookie：包含客户端发送给服务器的cookie信息。

这是是一个接口文档的请求头的示例：

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321
If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA"
Referer: https://example.com/login
Origin: https://example.com
Content-Length: 43

{"name": "John Doe", "age": 25, "email": "john.doe@example.com"}

Copy after login

11 接口请求示例

接口文档，需要提供接口的使用案例：以方便开发者理解接口的使用方法和调用流程。

12. 接口测试

一般来说，接口文档需要完善：接口测试的方法和测试结果，以便用户可以测试接口是否符合自己的需求，让用户用得放心~哈哈

The above is the detailed content of 12 points to note when sharing interface design documents. For more information, please follow other related articles on the PHP Chinese website!

Statement of this Website

The content of this article is voluntarily contributed by netizens, and the copyright belongs to the original author. This site does not assume corresponding legal responsibility. If you find any content suspected of plagiarism or infringement, please contact admin@php.cn

Hot AI Tools

Undresser.AI Undress

AI-powered app for creating realistic nude photos

AI Clothes Remover

Online AI tool for removing clothes from photos.

Undress AI Tool

Undress images for free

Clothoff.io

AI clothes remover

Video Face Swap

Swap faces in any video effortlessly with our completely free AI face swap tool!

Hot Article

Assassin's Creed Shadows: Seashell Riddle Solution

1 months ago By DDD

What's New in Windows 11 KB5054979 & How to Fix Update Issues

3 weeks ago By DDD

Where to find the Crane Control Keycard in Atomfall

1 months ago By DDD

How to fix KB5055523 fails to install in Windows 11?

2 weeks ago By DDD

InZoi: How To Apply To School And University

3 weeks ago By DDD

Hot Tools

Notepad++7.3.1

Easy-to-use and free code editor

SublimeText3 Chinese version

Chinese version, very easy to use

Zend Studio 13.0.1

Powerful PHP integrated development environment

Dreamweaver CS6

Visual web development tools

SublimeText3 Mac version

God-level code editing software (SublimeText3)

Hot Topics

Where is the login entrance for gmail email?

7771

Java Tutorial

1644

CakePHP Tutorial

1399

Laravel Tutorial

1296

PHP Tutorial

1234

Related knowledge

PHP 8.4 Installation and Upgrade guide for Ubuntu and Debian Dec 24, 2024 pm 04:42 PM

PHP 8.4 brings several new features, security improvements, and performance improvements with healthy amounts of feature deprecations and removals. This guide explains how to install PHP 8.4 or upgrade to PHP 8.4 on Ubuntu, Debian, or their derivati

7 PHP Functions I Regret I Didn't Know Before Nov 13, 2024 am 09:42 AM

If you are an experienced PHP developer, you might have the feeling that you’ve been there and done that already.You have developed a significant number of applications, debugged millions of lines of code, and tweaked a bunch of scripts to achieve op

How To Set Up Visual Studio Code (VS Code) for PHP Development Dec 20, 2024 am 11:31 AM

Visual Studio Code, also known as VS Code, is a free source code editor — or integrated development environment (IDE) — available for all major operating systems. With a large collection of extensions for many programming languages, VS Code can be c

Explain JSON Web Tokens (JWT) and their use case in PHP APIs. Apr 05, 2025 am 12:04 AM

JWT is an open standard based on JSON, used to securely transmit information between parties, mainly for identity authentication and information exchange. 1. JWT consists of three parts: Header, Payload and Signature. 2. The working principle of JWT includes three steps: generating JWT, verifying JWT and parsing Payload. 3. When using JWT for authentication in PHP, JWT can be generated and verified, and user role and permission information can be included in advanced usage. 4. Common errors include signature verification failure, token expiration, and payload oversized. Debugging skills include using debugging tools and logging. 5. Performance optimization and best practices include using appropriate signature algorithms, setting validity periods reasonably,

PHP Program to Count Vowels in a String Feb 07, 2025 pm 12:12 PM

A string is a sequence of characters, including letters, numbers, and symbols. This tutorial will learn how to calculate the number of vowels in a given string in PHP using different methods. The vowels in English are a, e, i, o, u, and they can be uppercase or lowercase. What is a vowel? Vowels are alphabetic characters that represent a specific pronunciation. There are five vowels in English, including uppercase and lowercase: a, e, i, o, u Example 1 Input: String = "Tutorialspoint" Output: 6 explain The vowels in the string "Tutorialspoint" are u, o, i, a, o, i. There are 6 yuan in total

How do you parse and process HTML/XML in PHP? Feb 07, 2025 am 11:57 AM

This tutorial demonstrates how to efficiently process XML documents using PHP. XML (eXtensible Markup Language) is a versatile text-based markup language designed for both human readability and machine parsing. It's commonly used for data storage an

Explain late static binding in PHP (static::). Apr 03, 2025 am 12:04 AM

Static binding (static::) implements late static binding (LSB) in PHP, allowing calling classes to be referenced in static contexts rather than defining classes. 1) The parsing process is performed at runtime, 2) Look up the call class in the inheritance relationship, 3) It may bring performance overhead.

What are PHP magic methods (__construct, __destruct, __call, __get, __set, etc.) and provide use cases? Apr 03, 2025 am 12:03 AM

What are the magic methods of PHP? PHP's magic methods include: 1.\_\_construct, used to initialize objects; 2.\_\_destruct, used to clean up resources; 3.\_\_call, handle non-existent method calls; 4.\_\_get, implement dynamic attribute access; 5.\_\_set, implement dynamic attribute settings. These methods are automatically called in certain situations, improving code flexibility and efficiency.

See all articles