Full version of API Interface Specification (Continued)
The overall specification recommends RESTful implementation.
agreement
The API always uses HTTPs to communicate with users, ensuring the security of data transmission.
The domain name
The API should be deployed under a private domain as much as possible. api.example.com
If you determine that the API is simple and will not be extended further, consider placing it under the main domain. example.org/api/
API version control
You should put the VERSION number of the API in the URL. api.example.com/v{n}/ Another option, less convenient and intuitive than putting the version number in the URL, is to put it in the HTTP header. Github takes this approach.
Multiple versions coexist and are released increments. V {n} N indicates the version number, which can be classified into integer and floating point integer versions. It has all apis of the current version, for example, v1 and v2. Floating point: indicates a small version and only provides supplementary API functions. Other apis call apis of a larger version, for example, V1.1 v2.2 by default
API path rules
The path, also known as the endpoint, represents the specific URL of the API. In a RESTful architecture, each url represents a resource, so there can be no verbs in the url, only nouns, and the nouns usually correspond to the table names in the database. Generally speaking, tables in a database are “collections” of the same records, so nouns in apis should also be plural. For example, if there is an API that provides information about zoos, as well as information about various animals and employees, its path should look like this.
Api.example.com/v1/products api.example.com/v1/users api.example.com/v1/employee…
HTTP Request Mode
The specific types of operations on resources are represented by HTTP verbs. There are four commonly used HTTP verbs (the corresponding SQL commands are in parentheses). GET (SELECT) : Retrieves one or more resources from the server. POST (CREATE) : Creates a resource on the server. PUT (UPDATE) : Updates the resource on the server (the client provides the full resource after the change). DELETE (DELETE) : deletes resources from the server.
Here are some examples.
GET /product: lists all commodities. POST /product: creates a commodity. GET /product/ID: obtains information about a specified commodity. GET /product/ID/purchase/ GET /product/ID/purchase/ GET /product/ID/purchase/ GET /product/ID/purchase/
Filtering information
If there are many records, the server cannot return them all to the user. The API should provide parameters that filter the return results.
Here are some common parameters. ? Limit =10: Specify the number of records to return? Offset =10: Specifies the start of the return record. ? Page =2&per_page=100: Specifies the number of pages and the number of records per page. ? Sortby = name&ORDER = ASC: Specifies by which attribute the return results are sorted, and in what order. ? Producy_type =1: specifies the filter criteria
API pass parameter
There are four types of input parameters:
Address bar parameters * restful address bar parameters/API /v1/product/122 122 indicates the product number, and information about product 122 is obtained. * For the query string in GET mode, see the filtering information section. Request Body data Cookie Request Header
Cookies and headers are generally used for OAuth authentication
Return the data
As long as the API successfully receives the request, it cannot return HTTP status beyond 200. To ensure smooth data interaction between the front and back ends, it is recommended to standardize data return and encapsulate data in a fixed format.
Interface returns template:
{the status: 0, data: {} | | [], MSG: “}
Status: indicates the status of the interface
0: Indicates that the interface is successful. <0: indicates that an exception occurs
Data Indicates the master Data of the interface
Can return an array or JSON object, depending on the actual situation
Msg
When the status! =0 should have an error message
Requirements for non-restful apis
In the actual service development process, there may be various apis that cannot be implemented by simple restful specifications. Therefore, some apis are required to break through restful specifications. In particular, the API design of mobile Internet requires some specific apis to optimize the interaction of data requests.
Page level API
All data needed for the current page is returned through one interface at a time
For example,
API /v1/get-home-data Returns all data used by the home page
This kind of API has a very bad address and needs to change whenever business requirements change.
Custom composition API
The multiple interfaces that the current user needs to load content in the first time are combined into one request and sent to the server. The server merges all data back at one time according to the request content. Compared with the page-level API, it has higher flexibility and can easily realize the page-level API function.
specification
Address: API/v1 / batApi
Passing in parameters:
data:[
{url:’api1′,type:’get’,data:{…}},
{url:’api2′,type:’get’,data:{…}},
{url:’api3′,type:’get’,data:{…}},
{url:’api4′,type:’get’,data:{…}}
]Return the data
{status:0,msg:”,
data:[
{status:0,msg:”,data:[]},
{status:-1,msg:”,data:{}},
{status:1,msg:”,data:{}},
{status:0,msg:”,data:[]},
]
}
Api co-built platform
RAP is a GUI WEB interface management tool. In RAP, you define the URL of the interface, the format of the request & response details, and so on. By analyzing this data, RAP provides automated tools like MOCK services, test services, and more. RAP also provides a number of enterprise-level capabilities to help organizations and teams work efficiently.
What is a RAP?
In the development pattern of the front and back end separation, we usually need to define an interface document to specify the details of the interface. Such as the address of a request, how many parameters, parameter name and type meaning, and so on. RAP first facilitates the team to input, view and manage these interface documents, and through the analysis of structured document data, reuse and generate self-test data, provide self-test console and so on… Greatly improve the efficiency of development.
The characteristics of RAP
Powerful GUI tools for a powerful user experience, you will love using RAP to manage your API documents.
As soon as the perfect MOCK service documentation defines it, all the interfaces are ready. With MockJS, no matter how complex your business model is, it does a great job of satisfying it.
RAP, a huge user base, has been used by more than 200 large-scale projects in Alibaba, as well as many famous companies and open source personages. RAP has grown with these businesses, focusing on detail and quality and standing up to the test.
Free + Professional support RAP is free and your technical inquiries will be answered within 24 hours. In most cases, you get a response within an hour.
RAP is a visual interface management tool by analyzing the interface structure, dynamically generating simulation data, verifying the correctness of the real interface, around the interface definition, through a series of automation tools to improve our collaboration efficiency. Our slogan: Improve efficiency, go home for dinner!
Use video
Source: Taobao video Youku
RAP Learning Center
Regularly updated step-by-step video tutorials
THX. Making. IO/RAP/study. H…
Refer to the link www.ruanyifeng.com/blog/2014/0… Github.com/thx/RAP/wik…