12 points to note when sharing interface design documents
Apr 24, 2023 am 10:58 AMPreface
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~
- 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.
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
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.
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 as1~10
, if it is an enumeration value, That is the enumeration range, such asACTIVE, 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 |
- Parameter name: describes the name of the response parameter.
- Parameter type: describes the data type of the response parameter, such as
- String, Integer
, etc.
Parameter format: describes the data format of the response parameter, such as - yyyy-MM-dd, HH:mm:ss
, etc.
Parameter description: Detailed description of the meaning of the response parameters. - Value range: Describes the value range of the response parameter, such as
- integer range, string length, etc. Required: Describes whether the response parameter is required.
- Example value: Provide an example value for this response parameter so that developers can better understand and use this parameter.
code, msg, data:
{ "code": 0, "message": "success", "data": { "name": "Tom", "age": 20, "gender": "男" } }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 information | Meaning | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Illegal request parameter | 1002 | ||||||||||
The corresponding user information was not found based on the given user ID | ##1003 | ||||||||||
Database access error | 7.接口安全定義接口文檔時,對于一些需要保護的接口,也需要考慮接口的安全,例如權限管理、防止 SQL 注入等。 因此,接口文檔應當包含接口的安全性說明:例如接口的訪問授權方式、數據傳輸加密方式等。此外,接口文檔還應該對于敏感數據和操作進行標注,方便使用者注意隱私和安全問題。 8. 接口版本管理在接口文檔定義時,接口版本管理是非常重要的一個方面。由于軟件項目的迭代和升級,接口可能會隨著版本的變化而發(fā)生變化。為了避免接口變化給用戶帶來不必要的困擾,需要對接口進行版本管理。 以下是一些常用的接口版本管理方法:
無論采用何種方法,接口版本管理都應該得到充分的考慮。在接口版本變化時,需要及時更新接口文檔(詳細描述版本的變化、兼容性問題、版本切換方式等),以確保用戶能夠獲得最新的接口信息。 9. 維護接口文檔更新迭代如果接口發(fā)生了變更,比如參數有哪些變更,錯誤碼變更等等,都需要維護到文檔上。同時需要登記變更的記錄。
10.明確請求頭有哪些接口文檔,是需要寫清楚的請求頭的。接口文檔的請求頭可以看到以下的信息:
這是是一個接口文檔的請求頭的示例: 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"} 11 接口請求示例接口文檔,需要提供接口的使用案例:以方便開發(fā)者理解接口的使用方法和調用流程。 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![]() Undress AI ToolUndress images for free ![]() Undresser.AI UndressAI-powered app for creating realistic nude photos ![]() AI Clothes RemoverOnline AI tool for removing clothes from photos. ![]() Clothoff.ioAI clothes remover ![]() Video Face SwapSwap faces in any video effortlessly with our completely free AI face swap tool! ![]() Hot Article
Grass Wonder Build Guide | Uma Musume Pretty Derby
3 weeks ago
By Jack chen
Roblox: 99 Nights In The Forest - All Badges And How To Unlock Them
3 weeks ago
By DDD
Uma Musume Pretty Derby Banner Schedule (July 2025)
4 weeks ago
By Jack chen
Today's Connections hint and answer 3rd July for 753
1 months ago
By Jack chen
Windows Security is blank or not showing options
4 weeks ago
By 下次還敢
![]() Hot Tools![]() Notepad++7.3.1Easy-to-use and free code editor ![]() SublimeText3 Chinese versionChinese version, very easy to use ![]() Zend Studio 13.0.1Powerful PHP integrated development environment ![]() Dreamweaver CS6Visual web development tools ![]() SublimeText3 Mac versionGod-level code editing software (SublimeText3) ![]() The core method of building social sharing functions in PHP is to dynamically generate sharing links that meet the requirements of each platform. 1. First get the current page or specified URL and article information; 2. Use urlencode to encode the parameters; 3. Splice and generate sharing links according to the protocols of each platform; 4. Display links on the front end for users to click and share; 5. Dynamically generate OG tags on the page to optimize sharing content display; 6. Be sure to escape user input to prevent XSS attacks. This method does not require complex authentication, has low maintenance costs, and is suitable for most content sharing needs. ![]() To realize text error correction and syntax optimization with AI, you need to follow the following steps: 1. Select a suitable AI model or API, such as Baidu, Tencent API or open source NLP library; 2. Call the API through PHP's curl or Guzzle and process the return results; 3. Display error correction information in the application and allow users to choose whether to adopt it; 4. Use php-l and PHP_CodeSniffer for syntax detection and code optimization; 5. Continuously collect feedback and update the model or rules to improve the effect. When choosing AIAPI, focus on evaluating accuracy, response speed, price and support for PHP. Code optimization should follow PSR specifications, use cache reasonably, avoid circular queries, review code regularly, and use X ![]() User voice input is captured and sent to the PHP backend through the MediaRecorder API of the front-end JavaScript; 2. PHP saves the audio as a temporary file and calls STTAPI (such as Google or Baidu voice recognition) to convert it into text; 3. PHP sends the text to an AI service (such as OpenAIGPT) to obtain intelligent reply; 4. PHP then calls TTSAPI (such as Baidu or Google voice synthesis) to convert the reply to a voice file; 5. PHP streams the voice file back to the front-end to play, completing interaction. The entire process is dominated by PHP to ensure seamless connection between all links. ![]() 1. Maximizing the commercial value of the comment system requires combining native advertising precise delivery, user paid value-added services (such as uploading pictures, top-up comments), influence incentive mechanism based on comment quality, and compliance anonymous data insight monetization; 2. The audit strategy should adopt a combination of pre-audit dynamic keyword filtering and user reporting mechanisms, supplemented by comment quality rating to achieve content hierarchical exposure; 3. Anti-brushing requires the construction of multi-layer defense: reCAPTCHAv3 sensorless verification, Honeypot honeypot field recognition robot, IP and timestamp frequency limit prevents watering, and content pattern recognition marks suspicious comments, and continuously iterate to deal with attacks. ![]() PHP ensures inventory deduction atomicity through database transactions and FORUPDATE row locks to prevent high concurrent overselling; 2. Multi-platform inventory consistency depends on centralized management and event-driven synchronization, combining API/Webhook notifications and message queues to ensure reliable data transmission; 3. The alarm mechanism should set low inventory, zero/negative inventory, unsalable sales, replenishment cycles and abnormal fluctuations strategies in different scenarios, and select DingTalk, SMS or Email Responsible Persons according to the urgency, and the alarm information must be complete and clear to achieve business adaptation and rapid response. ![]() PHP does not directly perform AI image processing, but integrates through APIs, because it is good at web development rather than computing-intensive tasks. API integration can achieve professional division of labor, reduce costs, and improve efficiency; 2. Integrating key technologies include using Guzzle or cURL to send HTTP requests, JSON data encoding and decoding, API key security authentication, asynchronous queue processing time-consuming tasks, robust error handling and retry mechanism, image storage and display; 3. Common challenges include API cost out of control, uncontrollable generation results, poor user experience, security risks and difficult data management. The response strategies are setting user quotas and caches, providing propt guidance and multi-picture selection, asynchronous notifications and progress prompts, key environment variable storage and content audit, and cloud storage. ![]() PHPisstillrelevantinmodernenterpriseenvironments.1.ModernPHP(7.xand8.x)offersperformancegains,stricttyping,JITcompilation,andmodernsyntax,makingitsuitableforlarge-scaleapplications.2.PHPintegrateseffectivelyinhybridarchitectures,servingasanAPIgateway ![]() Select the appropriate AI voice recognition service and integrate PHPSDK; 2. Use PHP to call ffmpeg to convert recordings into API-required formats (such as wav); 3. Upload files to cloud storage and call API asynchronous recognition; 4. Analyze JSON results and organize text using NLP technology; 5. Generate Word or Markdown documents to complete the automation of meeting records. The entire process needs to ensure data encryption, access control and compliance to ensure privacy and security. ![]() |