Querying (query) and identification (Identify)

Querying (query) and identification (Identify)

Related article: Some summary of RESTful API URI design.

Problem Scenario: Delete a resource (resources), how is the URI designed?

Application Example: Remove the product with the name IPhone 6.

Does it feel simple? According to the application example, we implement the following code:

public class ProductsController : ApiController{    [HttpDelete]    [Route("api/products")] public async Task<HttpResponseMessage> DeleteByProductName(string productName) { ... }}

Client calls:

delete /api/products?productName=iPhone 6

Some articles about RESTful API URIs on the web, are examples of nature, that is, do not really apply to real applications, such as the deletion of a resource URI, it will tell you should be the design delete /api/products/{productId} is better:, ProductId is the product's unique identity, Delete resource must pass unique identification? This can be true in the example application, but the scenario in the actual application is often hundreds of times times more complex than the example, for example, we can make the above example more complex:

• Remove a user under the name IPhone 6 and the system for IOS 8 products

For the application example above, how do we design the URI? Do you still have to stick with the "delete resource must be uniquely identified"? If this is the case, our solution is "simple" more, yes, right, first query and then delete, it is so simple, but always feel what is wrong, there is a voice in the heart (should not be so ah, there must be other solutions). In addition, the Delete operation contains ?productName=iPhone 6 , this way is not also feel very strange, why? Are we generally designing MVC URLs or WebAPI URIs? The following is usually followed by the query condition, since it is the query condition, that with the Delete operation, it is very "strange", we look at a sample GitHub API:

"user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}"

? Q={query} is generally used for URI GET operations, can that be used for other operations? Let's first look at the authoritative definition of Query:

The query component contains non-hierarchical data, along with data on the Path Component (Section 3.3), serves to ID Entify A resource within the scope of the URI ' s scheme and naming authority (if any). The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") characte R or by the end of the URI.

Although the text is short, but the amount of information is very large, mainly about two content: what is Query? What is the role of Query?

Non-hierarchical the meaning of non-hierarchical structure, that is, the URI of the/(structure), query does not contain non-hierarchical structure of data, a simple word,? and then before and # , this part of the content is Query, such as User_search_ In the URL q={query}{&page,per_page,sort,order} , what is the function of Query? Identify resources (identify a resource), it should be noted that the above paragraph, the slightest mention of the word Get, in fact, the URI and HTTP Method is not a half-dime relationship, not one by one correspondence, this is my own before a very deep misunderstanding, To correct it over.

Well, the query question has been solved, and we're going to design the URI for the application example above, in roughly two scenarios:

• delete /api/users/1/products?productName=iPhone 6&&system=iOS 8
• delete /api/products?userId=1&&productName=iPhone 6&&system=iOS 8

The difference between the two URI designs is that the first URI puts the user in Path, and the second URI places the user in Query. What kind of design is good? On this question, in fact, I do not have a definite idea, and then search the Internet a lot of information, but are some general concepts, and no specific analysis of the problem, by chance to see Nanyi this blog "RESTful API Design Guide", the content is a lot of concepts and simple examples, But there was a buddy's comment that caught my attention (meeting a companion) and I copied it directly under:

You are now working on an interface based on the RESTful API architecture. But there are some problems that make you very troubled:

If each device (devices) has more than one device picture (images), then according to restful, our URI is designed as follows:

Now the design:

• Get/devices/id/images: Get all pictures of a device
• GET/DEVICES/ID/IMAGES/ID: Get a picture of a device (we don't offer a fix, some people think it's meaningless)
• Post/devices/id/images: Add a picture to the specified device
• PUT/IMAGES/ID: Modify a picture (in doubt)
• DELETE/IMAGES/ID: Delete a picture (in doubt)

I think the reasonable design is:

• PUT/DEVICES/ID/IMAGES/ID: Modify a picture of a device
• DELETE/DEVICES/ID/IMAGES/ID: Delete a picture of a device

See, for the modification and deletion of a picture, I have doubts, now delete is directly through the image ID to delete (regardless of which device the picture belongs to). Does it actually fit the standard of restful? The reason for their design is that because the image itself has its own image ID, why delete it directly through the ID, but also have to specify a picture of a device, and then delete.

RESTful emphasis on the uniqueness of resources, IMAGES/ID is actually the only picture resources, and/devices/id/images/id is the only picture of the device, then, I do not know which URI should be used in the design.

See above is not a bit familiar with the bright, and our application example actually exist the same question, but unfortunately, no one reply to this buddy, I want to reply to him, but I do not understand, what reply? Well, since the discovery of the people of Freemasonry, it is more courageous to search, and later in the vast Google search, and stumbled upon this post: Designing a REST API by URI vs query string.

The friend's question is, grandparents (grandparent) below is the parents, parents below is the child, that if go to query the child, how to design the URI? Look at this guy. Three URI designs:

• GET /myservice/api/v1/grandparents/{grandparentID}/parents/children?search={text}
• GET /myservice/api/v1/parents/{parentID}/children?search={text}
• GET /myservice/api/v1/children?search={text}&grandparentID={id}&parentID=${id}

Regarding this question, the great God has made the detailed answer, each answer can write an article, I probably saw several, is also foggy, everybody if has the English good, can translate this post, I think is very valuable.

Here's my own experience, first of all, the hierarchy in the URI is not necessarily applicable, such as the above example, the situation is now three, but in fact is multipolar, grandparents have zuzu parents and so on, so, if you want to use a hierarchy to embody the URI, it is not desirable, and secondly, What exactly is the resource you want to request? Grandparents, parents, or children? If it is a child, then regardless of the URI design, the last word in the hierarchy must be childrens, which is certain, if there is a hierarchical structure relationship, is designed to Query? or Path? Let's take a look at some reply:

I believe I has already thoroughly beaten this to death, but query strings is not for "filtering" resources. They is for identifying your resource from non-hierarchical data. If you had drilled down your hierarchy with your path by Going/person/{id}/children/and you were wishing to identify a s Pecific child or a specific set of children, you would use some attribute the applies to children is identifying and Include it inside the query.

Again, Query is not a filter resource, but a Identify resource (non-hierarchical structure data), he designed the URI: /person/{id}/children/ , I think this is a good design, the structure of the genealogy can be abstracted out, people have children, whether it is grandparents, or parents, this hierarchical relationship is determined, By identifying a certain person, and then determining his child, so that more specific, as far as the logo, can be placed in the Query, to specifically identify the resources under this hierarchy, so sometimes it may not be your URI problem, but your URI design problem.

Looking back at the beginning of our design of the two URIs, in fact, I think it is possible, the user as a hierarchical structure can be, as the identity of resources (Query) can also, after all, they actually do not have a particularly strong hierarchical relationship, if there are some hierarchical relationship, for the most end of the resource, the identity of resources can be made explicit For example, delete the picture that the Buddy's ImageID, this can directly identify a specific picture, or can not use Device to identify, this problem, I myself now feel, and no uniqueness, the key to see the specific application scenario, and the RESTful API URI understanding, but anyway, Design the URI, must be concise, and let others understand.

I, delete the picture of the man, and the family tree brother, the problem, although the specific application scenario is not the same, but in fact, is the same, I feel like this kind of problem, you can delve into the next, this blog post to this.

Add some REST-related articles:

• Rest-ful URI Design ( Great)
• REST API Quick Tips
• REST
• RESTful API Design Guide
• REST Brief ( the best in the garden )
• Understanding REST
• REST API Design-resource Modeling
• Best practices for Better RESTful API

Querying (query) and identification (Identify)