At the beginning of a project, the interface design needs to be confirmed: how data will be transferred, what format and protocol will be used and how to ensure security. If a project’s interface is poorly designed — for example, without security considerations, and parts of the API have to be reworked later to add security validation — then the front end (Android, iOS, and Web in general) will have to change the entire project, which may even lead to the embarrassment of not being used in the previous release.

This article is about what I think a good interface should look like.

design

Use RESTful API design.

agreement

HTTPS ensures the convenience and security of HTTP.

The domain name

If possible, use an exclusive domain name, such as Github:

version

You should put the version number in the URL. If the API is changed, you should ensure that the old VERSION of the API continues to serve for a period of time.

https://api.example.com/v1/Copy the code

Paths and Resources

In Restful apis, each path represents a resource in the Internet. So urls should be nouns, and since they are mostly collections of resources, they should be plural. If it is a subordinate resource, it should obey the subordinate relationship. Here are some examples: ‘

  • https://api.example.com/v1/posts
  • https://api.example.com/v1/posts/{postId}
  • https://api.example.com/v1/posts/{postId}/comments

HTTP verbs

HTTP verbs correspond perfectly to database add, delete, and alter operations, so we’ll match HTTP verbs to our add, delete, and alter operations:

  • GET: Queries data
  • POST: Adds data
  • PUT: Updates data (the client provides the full resource after the change)
  • PATCH: Updates data (the client updates certain attributes)
  • DELETE: deletes data

The sample

Here are some examples with HTTP verbs and paths:

  • GET /posts: Get all articles
  • POST /posts: Create an article
  • GET /posts/{postId}: Gets the article information with the specified Id
  • PUT /posts/{postId}: Modifies the article information of the specified Id (the client needs to provide all attributes)
  • PATCH /post/{postId}: Modifies the article information of the specified Id (the client provides some attributes to be modified)
  • DELETE /post/{postId}: Deletes the article with the specified Id
  • GET /posts/{postId}/comments: gets all comments for the article with the specified Id
  • POST /posts/{postId}/comments: Creates a comment under the specified article Id

Query Query

It is impossible for us to GET all the resources at once during GET query, so we need to provide some query conditions.

Here are some common queries:

  • ? Index =2&size=20: second page 20 items per page

  • ? Sortby =name&order=asc: sortby specified rule and order

Global information

Global generic information should be placed in the request header, avoiding Query concatenation, as in:

  • APPID (Android/iOS/H5)
  • APPVER (Version number)
  • CHANNEL Number
  • App-build-num (internal small version number)
  • TOKEN
  • NETWORK (NETWORK environment)
  • LANGUAGE

To transmit data

Request

Data is transferred in JSON format, and if a file needs to be uploaded, a form is submitted.

Response

Data is transmitted in JSON format. Content-type is always set to Application/JSON.

The response format should be uniform. Here’s an example:

The name type meaning
code int Status code
message String State information
data List or Object data
time long The time stamp

Specific responses are as follows:

'code' : 0, 'the message:' success 'and' data ': [{}, {}, {}], / / return a set of' time ': 1472435695000Copy the code

Or return some data:

'code': 0, 'message': 'get success ', 'data': {}, // return an object 'time': 1472435695000Copy the code

security

To ensure secure communication between the client and the server, HTTPS is used.

The Oauth 2.0 protocol is used for identity authentication. After a user logs in, a token is saved on the client, avoiding persistent storage of the user name and password on the client. Each time you access an API that requires authentication, you must carry a token for access.

Avoid null Pointers

The API should be designed to help the front end avoid null pointer exceptions. Default values should be returned when some fields or attributes are empty: String returns “”, int returns 0, Object returns {}, Array or List returns [].

reference

Loshine. Me /2016/09/01/…