API interface design specifications

An overview of the

This article shares the API interface design specification for the purpose of providing a reference for developers.

Norms are dead, people are alive, hope their own norms, not to be hit in the face.

Route Naming Convention

Request way

Request parameters

Query

url? The following parameters store the parameter data of the request interface.

Header

The request header contains public parameters, requestId, token, and encrypted fields.

Body

The Body contains the parameter data of the request interface.

Public parameters

APP client request

The WEB client request

The caller requests an appKey (for request) and a secretKey (for encryption) from the server.

Safety norms

Sensitive parameters are encrypted

The login password and payment password must be encrypted before transmission. You are advised to use asymmetric encryption.

Other specifications

• It is recommended that parameters be named with a hump and start with a lowercase letter.
• RequestId is recommended to carry a unique identifier to track the problem.

Returns the parameter

If paging data is returned, the format is as follows:

{
    "code": 1,
    "showMsg": "success",
    "errorMsg": "",
    "data": {
        "list": [],
        "pagination": {
            "total": 100,
            "currentPage": 1,
            "prePageCount": 10
        }
    }
}
Copy the code

Safety norms

Desensitization of sensitive data

The user’s mobile phone number, user email, ID number, payment account number, mailing address and so on should be desensitized, and part of the data should be processed with asterisk.

Other specifications

• It is recommended that the property name be named using the hump and start with a lowercase letter.
• If the property value is null, the default value is returned strictly by type.
• Value of the attribute of the amount type/time and date type. If the value is only used for display, it is recommended that the back end return a string that can be displayed.
• It is recommended that the backend return both the status code of the business logic and the corresponding copy.
• Do not return properties that are not needed by the caller.

Signature design

There is no specification for signature verification. You can choose to use symmetric encryption, asymmetric encryption, one-way hash encryption, etc. Share the original signature verification for your reference.

• Go Signature verification
• PHP Signature verification

Log Platform Design

The log platform facilitates fault locating and log statistical analysis.

You can use the ELK component to build the log platform. You can use Logstash to collect log files. You can use Elasticsearch engine to search and analyze the log files and finally display them on the Kibana platform.

Idempotent design

There is no guarantee that every call to the interface will return a result, considering network exceptions.

For example, when an order is created and we need to destock, the interface times out and the caller retries, will the inventory be deducted one more time?

There are two ways to solve this problem:

1. The server provides the corresponding query interface, and the caller will query after the request times out. If the query is found, it means that the request is processed successfully, and if the query is not found, it goes through the failure process.

The caller simply tries again, and the server guarantees that the result of one and more requests will be the same.

In the second scenario, you need the server’s interface to support idempotentiality.

The general design idea is as follows:

1. Get a globally unique Token before calling the interface
2. When the interface is invoked, the Token is placed in the Header Header
3. The Header Header is parsed to verify whether it is a valid Token. If it is not, a failure is returned
4. After the service logic is complete, associate the service result with the Token and set the expiration time
5. Do not re-obtain the Token during the retry. Use the last Token

summary

Current limiting design, circuit breaker design, downgrade design, these are not much to say, because most of them are not used, when used are basically added to the gateway with these functions.

Think of so much for the moment, the specification of this thing is not invariable, found inappropriate timely adjustment.

Are the input and output keys of your interface named with humps or underscores? Leave a message.

Recommended reading

• What exactly are the front-line technology managers doing?
• When a person gets promoted, it’s not just about ability, it’s about trust