Understanding and Design of restful Web APIs

Document directory

• Get
• Put
• Post
• Delete

The method mentioned in the previous article about Web APIs (how to implement restful web API authentication) is very simple and effective, I used this in my actual project. The Code has been stable after a period of time, so I plan to write a summary, A comprehensive example of Asp.net web API is provided in the recent period.

Understanding of the four HTTP methods

As we all know, HTTP has four methods: Get, post, put, and delete, which correspond to select, insert, update, and delete of the database respectively. The general tutorial is over here, in fact, it is not enough to know this, and it is not enough to turn various business operations into these four methods. Below I will give some design ideas. This is my summary of my own practice. If there are any mistakes, please correct them:

Get

Yes, that is, select. If this business operation does not change the server data, it can be abstracted into a get method, but it is not absolute. For example, many websites provide file downloads, it is reasonable to say that the download should not change the server data, so get is used, but many times the server also provides the download count. Do you think this does not change the server data? -- This is generally not the case, so get is still used. The following is an example of the get method:

• Retrieve the list of all employees
• Query certain employee information by PAGE
• Obtains information about an employee.
• Download an object
• Get the price of the currently entered item

In this case, get uses a considerable number of methods.

Put

When a record is updated, it is abstracted into a PUT method. Will this action be used a lot? This is much less than you think. Why? Because a large number of actions to modify records are not just a simple update action. For example, if a user wants to cancel an order, this operation seems to be modifying the status of an order record to "undo ", but it is actually much more complicated than this. We have a process for ordering. A user only initiates a request to withdraw an order to our server, transfer the order to the revocation process, rather than simply modifying the order record status. There are a series of actions, such as waiting for the Administrator to confirm and update the receivables, this action should be post rather than put. Most of the items that involve business processes are post, I will mention it later, while put is used in simple databases that do not involve business processes, such:

• The user modifies his/her personal information (assuming this modification does not require approval)
• The user edited an order for temporary storage (not transferred for execution ).

Post

On the surface, it seems to correspond to a database insert, but in fact, the put and post operations are widely used. It can be said that most business operations will be abstracted into post methods, for example:

• Add a user
• Submit an order
• Cancel an order
• Payment
• Pay for employees
• Submit a basic data modification application (approval required)
• Activate a product
• Reject an employee's Application

Think about it. These actions often involve a series of changes to several tables in the database. In this case, you cannot simply use put, but instead use post, this is critical to understanding that a XX request is submitted.

Delete

Corresponding to the delete statement of the SQL statement, it means to delete an object. Should it be used a lot? In fact, like put, it is used less than you think, because most of the time, the "delete" executed by our database is not a simple delete, and even most objects, we do not provide direct deletion. For example, users, in order to ensure data integrity, we have used many foreign key constraints in the database. It is impossible to delete a user record directly, we can only "deactivate" a user, indicating that this user is no longer in effect. Of course, this is not so absolute. If this is a newly added user and it is not referenced in other tables, you can delete it directly, this occurs when the Administrator adds a user, but finds that the user name is incorrect, but the user name cannot be modified. The administrator can only try to delete the user and then add it again, or "stop" the wrong user, but this will generate a completely meaningless user record. Delete is used in scenarios where you think that the delete method is required (in many cases, it is not required. It depends on your design). For example:

• Delete a user (probably failed)
• Delete a temporary order (this order has not been transferred to the processing process)
• Delete A system message

More specific Action Description

To be more specific, I will convert the examples above into a specific URI and Action Description:

Operation	Uri	HTTP Method	Description
Retrieve the list of all employees	/API/EMP/employees	Get
Query certain employee information by PAGE	/API/EMP/employees? Sex = M & page = 1 & numberperpage = 20	Get	Add parameters to the URI
Obtains information about an employee.	/API/EMP/employees/58	Get	58 is the employee ID. You can also design it as a user name.
Download an object	/API/fileservice/files/2832	Get	2832 is the file ID. Of course, you can design it as a file name or GUID.
Get the price of the currently entered item	/API/sale/Goods/32680	Get	32680 is the product ID.
The user modifies his/her personal information (assuming this modification does not require approval)	/API/admin/users/8642	Put	8642 is the user ID. In addition, you need to add the required information to the change.
The user edited an order for temporary storage (not transferred for execution ).	/API/sale/orders/234892	Put	234892 is the order ID. In addition, you need to carry the information required to modify the order.
Add a user	/API/admin/users	Post	Add the information required by the new user
Submit an order	/API/sale/orders	Post	Complete order information
Payment	/API/sale/pay	Post	Complete payment information, including the ID of the order to be paid
Pay for employees	/API/EMP/paysalary	Post	The complete information of the pay-as-you-go instance includes the employee ID, the month and amount of the pay-as-you-go instance.
Submit a basic data modification application (approval required)	/API/basic/modifymanufacture	Post	Complete information of the object to be modified, including the ID
Activate a product	/API/sale/activateproduct	Post	Information about the product to be activated, including the ID
Reject an employee's Application	/API/admin/approve	Post	Include the Application ID and reason for rejection.
Delete a user (probably failed)	/API/admin/users/567	Delete	567 indicates the ID of the user to be deleted.
Delete a temporary order (this order has not been transferred to the processing process)	/API/sale/orders/234892	Delete	234892 is the order ID
Delete A system message	/API/sys/messages/1008689021	Delete	1008689021 indicates the system message id.

The "API" in URI is fixed and used to distinguish it from the URI of a common webpage, the subsequent "EMP", "fileservice", "sale", "admin", "Basic", and "sys" can be considered as classification, for example, "pay for employees" and "employee information" are both in the "EMP" category. The remaining part is the object name or resource name, in fact, the complete URI address is the real resource name. Why is it a resource? Google the restful web API and look at the restful "R" to understand it. Simply put, we finally abstract all kinds of operations as resources and all business operations (no matter how complicated) all change to add, query, modify, and delete a resource, that is, the four HTTP methods mentioned above.

The get, put, and delete methods are obvious and easy to understand. In most cases, the resources of these methods actually correspond to a database table or a record, for example, "/API/admin/users" may correspond to the admin_user table in the database, "/API/admin/users/8642" corresponds to the user record whose ID is 8642 in the admin_user table.

The post method is not so straightforward. For example, "/API/EMP/paysalary", maybe the root of the database does not have a one-to-one table, and paysalary is an abstract business operation object, executing post on this object is equivalent to giving a salary to an employee. The actual action may involve the association of multiple tables, for example, you can insert a record into the payroll mark and payroll record in the employee table, a record in the company's financial table, a record in the operation log table, and a record in the system message table ......

This is my understanding of the design of Web APIs. What are the problems?