Identify RESTful API Resources

For such a feature implementation API: Users in the e-commerce site can click on a product, to the system to initiate a request, the system according to the rules of the business booking or big data, to produce a combination of products for consumers to choose. The user's request needs to be recorded for a more accurate push for the customer later.

According to the requirements, a restful API is designed, the following example is to facilitate the discussion, delete some of the fields.

Request:post/deal-requests{"customerId":"JBoss",  "Productsku":"123"}response:201created{"ID":"1101",  "customerId":"JBoss",  "Productsku":"123", "deal": {"ID":"2001",    " Price":200.00,     "Productskus": ["123","124"]  }}

Two colleagues raised objections and did not understand why they had done so. A more straightforward scenario should look like this:

Request:post/get-deal{"customerId":"JBoss",  "Productsku":"123"}response: $ok{"ID":"2001",  " Price":200.00,  "Productskus": ["123","124"]}

It seems easy to understand, initiate a getdeal request, and then return a deal content. But that doesn't fit the restful style. As to whether to use restful style, is another topic, suppose we are to do a restful style API.

RESTful is resource-centric, which also determines the URL of an API. So which resource should this AP correspond to?

The client wants to acquire deal resources, and if the client knows which deal, such as id=2001, it can get the details of the deal by the standard get method.

get/deals/2001

However, the client does not know which deal to return, which is determined by the logic of the server side. Even when the client makes a request, the deal object may not exist yet. Then whether the

POST/deals{  "customerId" "jboss",   "productsku" "123"}

This appears to be a standard creation deal API, but does not contain the information needed to create a deal, such as this deal price and related product information Productsku.

How can you create a new resource without the necessary information?

In addition, our deal may be generated by an external engine or another service, and if we need to provide an API to save the deal resources generated by these external systems, we can no longer use the standard format to create the deal, because we cannot differentiate the API through the contents of the body.

POST/deals{  "price"200.00,   "  Productskus", [" 123 "" 124 "]}

After analysis, we find that there should also be a deal-request resource, including CustomerID and Productsku attributes (in fact, time attributes). This information is also required to be recorded for systematic learning and use.

Another important attribute of deal-request resources is the deal resources associated with them. This is also the information that the client needs to use in our scenario. The client is not responsible for allocating which deal resources to Deal-request, let's not care about how this deal is produced. This is done by the server, which may be generated immediately from the deal-request information, or by a batch of proprietary services that are placed in the pool and then selected from a Deal-request association.

So the process becomes: the client issues a Deal-request creation request, the server reply 201 is created successfully, and the Deal-request resource is returned, which contains the associated deal resources. This understanding of the API is clear.

Identifying resources is an important work in the design of restful APIs. We tend to take a more straightforward, easy-to-implement and understandable design to avoid over-design. But with the development, the system slowly fell into chaos, because at first we did not have a deep analysis of the clear. It is actually more correct to grasp the nature of the problem in order to remain simple and stable.

Identify RESTful API Resources