I’m starting to study about web api’s and REST and I’m having a hard time to understand what is really a resource. Basically the book I’m reading says that a resource is a conceptual mapping to one or more entities. Searching on the internet I found this from a dissertation:
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
Which again says a resource is a conceptual mappings to one or more entities, but that says that any information that can be named can be a resource. The book also stresses that entity in this case doesn’t refer to business objects but can be really anything.
Now, this idea of resource seems pretty important, but I can’t grasp what really a resource is and why it should be a mapping.
So what is really a resource, why it should be a mapping to one or more entities and what are some examples?
A resource is simply something you can get through an uniform resource identifier (URI), i.e. a piece of information which has an URI associated with it.
Imagine an image funny-cat.jpg on your PC; only you can access it. This is not a resource. If, on the other hand, you install an HTTP server which points to the directory containing the image, you can now access the image through an URI similar to http://example.com/funny-cat.jpg; it’s now a resource.
Note that a resource may be static (an image in the previous example) or dynamic (http://example.com/latest-news). This means that a resource isn’t necessarily something which exists permanently on a server.
Also note that a resource has an URI, but doesn’t necessarily have only one URI. For instance, http://example.com/product/912/dell-poweredge-r420 and http://example.com/publicstore/dc2/product.aspx?id=912 may point to the same resource (here using URL rewriting technique).
In the quote in your answer, the key sentence is:
Any information that can be named can be a resource.
An image can be named (http://example.com/funny-cat.jpg). The list of latest news can be named (http://example.com/latest-news). The image stored on your PC with no HTTP server on it cannot be named (there is no URI you can give to CURL to get this image), therefore it is not a resource.
6
So what is really a resource, why it should be a mapping to one or more entities and what are some examples?
When in doubt about anything relating to REST, consider the question in the context of the web.
Here’s a flow:
- I want to read Bob’s homepage
- I know (probably because some other web page told me) that there is a http request handler with the id /user/bob/homepage
- I send GET /user/bob/homepage to the web server
- The web server uses the id /user/bob/homepage to lookup the http request handler
- The web server delegates the http request to the request handler it found
- The request handler sends back a representation of Bob’s homepage
In this example, /user/bob/homepage is the uniform resource identifier. What resource is it identifying? In this case, the resource is an http request handler that provides a representation of the concept “Bob’s homepage” by mapping that concept to an html document stored on the local file system OR a markdown document in a key-value store OR an xml representation of a result-set provided by some relational database plus a template OR a retrieval from a local cache OR ….
Consider some of the alternative uris you may have seen
ftp://localhost/user/bob/homepage
file:///ftproot/user/bob/homepage
Those aren’t two different identifiers for a single file, those are identifiers for two different resources that provide you with a copy of the file. We know they are different resources, because the second one still works when we shut down the ftp server.
mailto:[email protected]
A fun one – the concept is something like “a draft of an email with the to header set”. And the resource is… something in your mail client that generates a representation of an email with the to header set to this address?
It’s deliberately very fuzzy, and abstract, because that’s where the power comes from. Compare
- Google: GET /user/bob/homepage
- Server: 200
- Google’s 2M closest friends: GET /user/bob/homepage
- Server: 500
with this alternative
- Google: GET /user/bob/homepage
- Proxy: GET /user/bob/homepage
- “I don’t know what that is”
- “And I don’t know to represent it”
- Server: 200
- Proxy: 200
- “I still don’t know what that is”
- “But now that I know how to represent it, I’ll store a copy”
- Google’s 2M closest friends: GET /user/bob/homepage
- Proxy: 200
Why does that work? Because the requests identify the resource without constraining the implementation of the resource at all.
And finally, remember that Fielding isn’t describing the web; he’s asserting that the web scales because of the architectural principles on which it is based, and if you base a new application on those same principles, the new application will also be able to support web scale.