Understanding and design ideas for restful Web APIs

Distance from previous article about Web API (how to implement the authentication of RESTful Web API) A lot of time, the method mentioned in that article is very simple and effective, I used in the actual project, the code after a period of running, has been very stable, so I intend to write a summary , and provides a comprehensive example of an ASP. NET Web API during the most recent period.

Understanding of four HTTP methods

As is known to all, HTTP has four methods, GET, POST, put and delete, corresponding to the database of SELECT, INSERT, update and delete, the general tutorial said here is over, in fact, just know this is not enough, is not enough to turn a variety of business operations into these four methods. Here I give some design ideas, this is my own practice of the summary, if there is a fallacy, please do not hesitate to correct:

GET

Yes, it is SELECT, if this business operation will not change the server's data, then it can be abstracted into a get method, but also not absolute, for example, many Web sites provide file download, it should be said that the download should not change the server data, so with get, but many times the server also provides a download count, You're saying this doesn't change the server's data? -This is usually not the case, so get is still used. The following is an example of a Get method:

• Get a list of all employees
• Search for some employee information by condition of page
• Get information about an employee
• Download a file
• Get the price of the currently entered item

So it seems that get is using quite a lot of methods.

PUT

Update a record is abstracted into a put method, then this action will also use a lot of it? This is a lot less than you think, why? Because a large number of changes to record the action is not just a simple update action, such as the user to cancel an order, the operation surface appears to be modified an order record status of "undo", but actually more complex than this, our order is a process, The user revokes an order in fact just to our server to put forward a request to cancel the order, so that the order into the revocation process, rather than simply modify the status of the order record, there are a series of actions, such as: Waiting for the administrator to confirm, update the receivables information, the goods have been out of the library back into storage, write operations log, Send system notifications and so on, so this action should be post, not put, most of the things involved in the business process are post, which I'll mention later, and put is used for simple, non-business process-related database single record update, for example:

• The user modifies his or her personal information (assuming that the modification does not require approval)
• The user edited an order that was staged (not transferred to the execution process)

POST

The surface appears to correspond to a single insert of the database, but in fact the use of contrast put,post is much broader, it can be said that most business operations will be abstracted into the post method, for example:

• Add a user
• Submit an Order
• Cancel an Order
• Payment
• Pay for employees
• Submit a modification request for basic information (requires approval)
• Activating a product
• Dismiss an employee's application

Consider that these actions often involve a series of changes in the database of several tables, this time can not simply use put, but should use post, representing "submitted a XX request", understand this is critical.

DELETE

The deletion of the corresponding SQL statement means that deleting an object is not a lot of use. In fact, the same as put, use less than you think, because most of the time, our database execution of "delete" is not a simple delete, and even most objects, we do not provide direct deletion, such as users, in order to ensure the integrity of the data, we use a lot of foreign key constraints in the database, To delete a user record directly is not successful, we can only "deactivate" a user, indicating that this user no longer takes effect. Of course, the words are not so absolute, if this is a newly added user and does not refer to it in other tables, then it is really possible to delete it directly, this situation occurs when the administrator has just added a user, but found that the user name is wrong, and the user name is not modified, The administrator can only attempt to delete the user and then add it again, or "deactivate" the user, just to create a completely meaningless user record. Delete is used for situations where you think you need to provide a Delete method (which in many cases is not required, depending on your design), for example:

• Delete a user (most likely failed)
• Delete a staged order (this order has not been transferred to the processing process)
• Delete a system message

A more specific description of the action

To be more specific, I'll turn these examples into materialized URIs and action descriptions:

Operation	Uri	HTTP method	Description
Get a list of all employees	/api/emp/employees	GET
Search for some employee information by condition of page	/api/emp/employees?sex=m&page=1&numberperpage=20	GET	Take parameters in URI
Get information about an employee	/api/emp/employees/58	GET	58 is the ID of the employee, of course you can also design the user name
Download a file	/api/fileservice/files/2832	GET	2832 is the ID of the file, and of course you can design it as a filename or GUID
Get the price of the currently entered item	/api/sale/goods/32680	GET	32680 is the ID of the product
The user modifies his or her personal information (assuming that the modification does not require approval)	/api/admin/users/8642	PUT	8642 is the user's ID, in addition to bring the various information needed to modify
The user edited an order that was staged (not transferred to the execution process)	/api/sale/orders/234892	PUT	234892 is the ID of the order, plus a variety of information required to modify the order
Add a user	/api/admin/users	POST	Bring the information you need for the new user
Submit an Order	/api/sale/orders	POST	Bring your order complete information
Payment	/api/sale/pay	POST	Payment complete information that will contain information such as the ID of the order to be paid
Pay for employees	/api/emp/paysalary	POST	Complete information on the payroll will be included, including employee ID, month and amount paid, etc.
Submit a modification request for basic information (requires approval)	/api/basic/modifymanufacture	POST	Bring complete information about the object you want to modify, including the ID, and so on
Activating a product	/api/sale/activateproduct	POST	Bring information about the product you want to activate, including the ID, etc.
Dismiss an employee's application	/api/admin/approve	POST	Bring your Application ID, reason for refusal, etc.
Delete a user (most likely failed)	/api/admin/users/567	DELETE	567 is the ID of the user to be deleted
Delete a staged 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 the ID of the system message

The "API" in the URI is fixed and is used to differentiate it from the normal Web page URI, and the next "EMP", "Fileservice", "Sale", "admin", "basic" and "SYS" can be considered as categories, such as "Payroll for employees" and "Employee Information" These two "resources" are placed in the "EMP" in this category, the rest is the object name, or the name of the resource, in fact, the full URI address is exactly the real resource name, why called resources? Google a restful Web API, look at the restful "R" to understand, in short, we have all kinds of operations are finally abstracted as resources, all business operations (no matter how complex) is transformed into a resource of the additions and deletions, that is, the above mentioned four HTTP method.

The GET, put, and delete methods are quite obvious, so to understand, most of the time, the resources of these methods do indeed correspond to a table or a record of the database, for example, "/api/admin/users" may correspond to the Admin_user table in the database, and "/ api/admin/users/8642 "corresponds to this user record with ID 8642 in the Admin_user table.

Post method is not so straightforward, such as "/api/emp/paysalary", perhaps there is no one in the database directly corresponding to the table, Paysalary is an abstract business Operation object, To perform post on this object is equivalent to giving an employee a salary, the actual action may involve the linkage of multiple tables, such as the salary of the employee table, the Payroll record table inserted a record, the company financial table inserted a record, the Operation log table insert a record, System message table insert a record, etc. ......

Understanding and design ideas for restful Web APIs