I knew some name conversions of REST API, for example resource name should be plural, using different HTTP method with same URI to perform different action on that resource, etc.
But as URI should reflect relationship of resources, I am a little confused. Take SO as a example, when update a existed comment of a answer, URI should looks like:
PUT /{contextPath}/questions/{questionId}/answers/{answerId}/comments/{commentId}
But I feel awkward when using this so-called standard URI because:
It's a little verbose, especially when the hierarchical is very
deep.
questionId and answerId is completely unnecessary here, since
commentId is sufficient for server to identify a comment record.
So what's the appropriate way to deal with this? should I always follow name conversions, or make some changes when the relationship hierarchical of resources is very deep?
I emphatically disagree that "URI should reflect relationship of resources".
URIs are pointers to resources. That's it. There are conventions for making them human-readable, and therefore easier to work with. There is certainly no hard-and-fast rule that relationships should be modeled on the URI path. Feel free to model resources in a flat, rather than hierarchical manner. Use links to model relationships between the resources, and query parameters to narrow down collections.
It gives you more Options without haveing to make extra requests.
Thus allowing you to call functions that might require say a questionId.
When you only have the commentId you have to first query your questionId.
Depending on what your functions require. If you had specific info on the previous page and have to use it again in the next why query it twice? Unless it is sensitive which an questionId clearly is not.
Thats my opinion on how you should look at your addoption of the standard
I would simplify the route/URI to:
PUT /comments/{commentId}
along with at the corresponding RequestBody, perhaps some sort of DTO.
The URI should not have to show the hierarchy all the way from the context path. It can be the shortest URI that can uniquely identify the resource
Related
So I'm building a REST api and need to make some urls. The problem is, I'm running into some conflicting paths. For example:
GET <type>/<id> gets the details of an object of a given type and id
GET <type>/summary gets the summary of objects of a given type
This simplified example shows a problem occurs when an object has id "summary". What is the best way to solve this? From a REST puritan perspective, what should be the solution?
Here's some of my ideas:
Put the <id> in query parameters. From what I understand this is against standards
Put a keyword at the start of the url. Also against standards?
Disallow certain id values. Not something I want to enforce for all my users and use cases and different entrances into my system
I may have an alternative to this. What if we have both book as wel as the plural books. Then you can have:
/book/{id}
and
/books/summary
or
/books/count
The URL structure is not quite right to begin with so it's difficult to solve it in a clean way.
For the sake of discussion, let's assume <type> is a books resource. So the first URL is fine - you get a book of the given ID:
GET /books/<id>
However this is not:
GET /books/summary
Because it's a bespoke URL, which I guess has a use in your application but is not restful. A GET call should return one or more resources. However a "summary" is not a resource, it's a property of a resource and that's why you end up in this situation of having IDs mixed up with book properties.
So your best option would be to change this URL to something like this:
GET /books?fields=summary
By default GET /books would return all the resources, while GET /books?fields=<list_of_fields> will return the books but with only the chosen properties.
That will be similar to your previous URL but without the ID/property conflict, and will also allow you later on to retrieve resources with specific fields (without having to create new custom URLs).
Edit:
Regarding the count of books, it's still useful to reason in terms of resources. /books gives you one or more books, but it should not be used for meta-information about the collection, such as count, but also things like "most read book", or "books that start with the letter 'A'", etc. as that will make the resource more and more complex and difficult to maintain.
Depending on what you want to achieve I think there'd be two solutions:
Create a new resource that manages the collection of books. For example:
GET /bookcase
And that will give you information about the collection, for example:
{
"count": 1234,
"most_read": "<isbn>",
// etc. - any information that might be needed about the book collection
}
Or a search engine. You create a resources such as:
GET /book_search_engine/?query=
which would return a search result such as:
{
"count": 123,
"books": [
// Books that match the query
]
}
then a query like this would give you just the count:
// Search all the books, but provide only the "count" field
GET /book_search/?query=*&fields=count
Obviously that's a more involved solution and maybe not necessary for a simple REST API, however it can be useful as it makes it easier to create queries specific to a client.
This simplified example shows a problem occurs when an object has id "summary". What is the best way to solve this? From a REST puritan perspective, what should be the solution?
As far as REST is concerned, the URI are opaque. Spelling is absolutely irrelevant. You could use URI like
/a575cc90-2878-41fe-9eec-f420a509e1f0
/f871fff6-4c4e-48f7-83a4-26858fdb3096
and as far as REST is concerned, that's spot on. See Stefan Tilkov's talk REST: I Don't Think It Means What You Think It Does.
What you are asking about is URI design, how to adapt conventions/best practices to your particular setting.
One thing that will help is to recognize is that summary is a resource, in the REST/HTTP sense -- it is a document that can be represented as a byte sequence. All you need to do is figure out where that resource belongs (according to your local spelling conventions).
Continuing to borrow the "books" example used by others
# Here's the familiar "URI that identifies a member of the books collection"
/books/<id>
# Here's the summary of the /books collection
/summaries/books
Put the in query parameters. From what I understand this is against standards
Not as much as you might think. REST doesn't care. The URI spec expresses some views about hierarchical vs non hierarchical data. HTTP supports the notion of a redirect, where one resource can reference another.
GET /books?id=12345
302 Found
Location: /books/12345
You also have options for skipping a round trip, by returning the representation you want immediately, taking advantage of Content-Location
GET /books?summary
200 OK
Content-Location: /summaries/books
...
I have the same issue. And all the solutions seem a little off b/c REST best practices seem to suggest none of them are ideal.
You could have just one off-limit id, like all.
GET <type>/<id>
GET <type>/all/summary
It might even be possible to use a single symbol instead, such as ~ or _.
GET <type>/<id>
GET <type>/~/summary
How satisfying this solution seems is of course very subjective.
The singular/plural approach seems more elegant to me but despite most REST best practice guides saying not to do this. Unfortunately some words don't have distinct singular and plural forms.
This isn't perfectly conventional for how some like to define their rest endpoints.
But I would would enforce a pattern where "id" cannot be any string. Instead I would use a uuid and define my routes as such.
GET /books/{id:uuid}
GET /books/{id:uuid}/summary
And if you really want a verb in the URL without an identifier it is still technically possible because we know the {id:uuid} in the path must conform to the uuid pattern.
With that GET /books/summary is still distinct from GET /books/{id:uuid}
I have been doing RESTful APIs for quite a bit (exposing and consuming 3rd parties) and I see two following patterns popping up here and there. Each has pros and cons and neither is "clean" in my opinion.
So the situation is: you have a collection resource (e.g. "assets") and you want to expose some additional resources within a collection (e.g. subresources of the collection itself, not the asset, like aggregated view endpoint or some commands).
Two patterns I see are:
People create a RESTful collection resource like /assets/${asset-id} and expose everything else they need like GET /assets/owned, GET /assets/summary, POST /assets/recheck-inventory. This looks neat and concise but introduces a clash between ${asset-id} and nouns of sub-resource URLs (e.g. asset12345 and summary are in the same place in the URL).
Others do /assets/items/${asset-id} and expose everything like GET /assets/owned, GET /assets/summary and so on. This is cleaner from routing perspective and a bit more future-proof, but adds an extra noun in the route, which leads to confusion when people are trying to do POST /assets for example.
The "best practice" guidelines I went through thus far avoid the question altogether. I also understand that REST is a convention and not the standard, and there is a universal "it depends" answer. Still, I feel like there got to be a generic recommendation here.
Hence the question is: which of two you would use?
UPDATE: to clarify, let us assume that:
/assets/owned contains entities of different types, not assets, so it is not a query and you can GET/POST/DELETE items in it.
/assets/summary is an aggregation document (e.g. report with quantities for example)
/assets/recheck-inventory is a command (i.e. POST only)
Also, we want to stick with REST principles:
route's path shall identify an entity and its state uniquely.
query parameters alter which elements are returned, but do not change the payload format.
headers are for protocol-level information and do not change service logic (i.e. presentation, security, caching, etc.)
I don't like these approaches either, but be aware, that REST does not put constraint on how to design URI structure, so you can do whatever you feel right. Apparently the developers of these webservices felt this approach right.
I would do something like the following with your URIs, since I like flat URIs much better.
/assets/items/${asset-id}
-> /assets/${asset-id}
/assets/owned
-> /assets/?owned
-> /assets/?owned=true
/assets/summary
-> /assets-summary
-> /assets/ + "Prefer: return=minimal"
You can find more about the prefer header here, but be aware, that you need to register it by the vary header if you want it to be a secondary cache key.
A question about REST uri design. In the official web api tutorial i have seen the following uri:
Get a list of books by publication date: /api/books/date/2013-02-16
Following the rest principles it's not better using the following uri?
/api/books?date=2013-02-16
Thanks
There are no hard rules about were parameters should go in this case. Some place them in the URL path some add them to the query string. Do note that in REST there is no emphasis placed on the way URLs should look like. People create them hierarchically because it makes sense to do so given their domain e.g.:
/api/books/ # all books
/api/books/100 # details about the book with id=100
/api/books/mystery # all books in the mystery category
On the other hand, /api/books/date/2013-02-16 is a little bit of a stretch, again because people reason about hierarchies of resources and most of the times model their APIs as such, so given that they would expect /api/books/date to also return some books in a larger category than /api/books/date/2013-02-16 does. But in this case it doesn't really make sense, so maybe that's why you find /api/books?date=2013-02-16 to be a more natural choice.
I would also prefer /api/books?date=2013-02-16 in this case. But again, there are no hard rules on what the better choice is, see for example this: REST API Best practices: Where to put parameters?
They are equal. According to the URI standard, the path contains the hierarchical part of the identifier while the query part contains the non-hierarchical part. Now in the case of map reducing a collection you can consider the filter both hierarchical and non-hierarchical depending on your taste.
Btw. I prefer the param:value solution in the path and ending the URIs of the collections (or reduced collections) with slash, so: /api/books/date:2013-02-16/, but afaik. that is just best practice, not standard... :-)
According to the uniform interface constraint of REST, you have to apply existing standards over custom solutions, that's why we follow the URI standard in this case...
1) I assume query string component of an URL is also considered as being a part of identity of a resource?
2) If it indeed is considered as being a part of identity, are there any reasons why in REST we can't/shouldn't identify resources with URLs which contain query string components?
Thank you
If the resource you are addressing with a URL represents a collection of resources like http://yourdomain.com/customers it's a valid restful way to filter the result with query-parameters:
http://yourdomain.com/customers?minSalary=2000&maxAge=50
So yes, query-parameters are meaningful for identifying resources.
I think you root question is about using a query that would return a unique item.
/orders?ID=8
which would be the same resource as
/order/8
So there we have two URIs for the same resource. You might be asking is that ok, and it is perfectly fine to have multiple URIs to get the same resource. Generally you should link to a more 'canonical' URI, the shortest 'path' (hierarchally speaking) for a resource.
You shouldn't rely on query parameters generally, as it tends to lead towards awkward API designs. For example, if you want to know all the orders made by bob, you might be tempted to think "well, I'm filtering the orders" and so do
/orders?users=bob
Where as better way of thinking is "I want all users, just bob, just his orders", so you would instead do
/users/bob/orders
This is a simple URI that you would be able to link to from the 'user resource' for bob. Sadly though, this second approach can get a bit awkward when you want to say, look at orders from multiple users
/users/jack,jill,alice,bob/orders
It's workable, but very odd looking.
Simple question I'm having trouble finding an answer to..
If I have a REST web service, and my design is not using url parameters, how can I specify two different keys to return the same resource by?
Example
I want (and have already implemented)
/Person/{ID}
which returns a person as expected.
Now I also want
/Person/{Name}
which returns a person by name.
Is this the correct RESTful format? Or is it something like:
/Person/Name/{Name}
You should only use one URI to refer to a single resource. Having multiple URIs will only cause confusion. In your example, confusion would arise due to two people having the same name. Which person resource are they referring to then?
That said, you can have multiple URIs refer to a single resource, but for anything other than the "true" URI you should simply redirect the client to the right place using a status code of 301 - Moved Permanently.
Personally, I would never implement a multi-ID scheme or redirection to support it. Pick a single identification scheme and stick with it. The users of your API will thank you.
What you really need to build is a query API, so focus on how you would implement something like a /personFinder resource which could take a name as a parameter and return potentially multiple matching /person/{ID} URIs in the response.
I guess technically you could have both URI's point to the same resource (perhaps with one of them as the canonical resource) but I think you wouldn't want to do this from an implementation perspective. What if there is an overlap between IDs and names?
It sure does seem like a good place to use query parameters, but if you insist on not doing so, perhaps you could do
person/{ID}
and
personByName/{Name}
I generally agree with this answer that for clarity and consistency it'd be best to avoid multiple ids pointing to the same entity.
Sometimes however, such a situation arises naturally. An example I work with is Polish companies, which can be identified by their tax id ('NIP' number) or by their national business registry id ('KRS' number).
In such case, I think one should first add the secondary id as a criterion to the search endpoint. Thus users will be able to "translate" between secondary id and primary id.
However, if users still keep insisting on being able to retrieve an entity directly by the secondary id (as we experienced), one other possibility is to provide a "secret" URL, not described in the documentation, performing such an operation. This can be given to users who made the effort to ask for it, and the potential ambiguity and confusion is then on them, if they decide to use it, not on everyone reading the documentation.
In terms of ambiguity and confusion for the API maintainer, I think this can be kept reasonably minimal with a helper function to immediately detect and translate the secondary id to primary id at the beginning of each relevant API endpoint.
It obviously matters much less than normal what scheme is chosen for the secret URL.