1

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?

4

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.

  • Thanks @MainMa, so in that case, the image itself funny-cat.jpg is the entity and when we expose it on some endpoint on the server this endpoint becomes a mapping to that entity, so the resource is really the endpoint? Also, if I have some device (like a printer) and I expose one endpoint to interface with the device, the entity would be the device and the endpoint would be the resource, being a mapping to the entity? – user1620696 Jan 31 '15 at 13:53
  • @user1620696: What would be your definition of endpoint? – Arseni Mourzenko Jan 31 '15 at 14:02
  • Well I believe I got it wrong at first, reading your edit, a resource can have multiple URI's. As I understand an endpoint would be the URL that maps to the entity. – user1620696 Jan 31 '15 at 14:06
  • If the endpoint is an URL, then no, the resource is not the endpoint, like... a person is not a phone number (but a person can be reached by calling a phone number and may have several numbers). – Arseni Mourzenko Jan 31 '15 at 14:10
  • So in the example you gave the resource is just the image itself after an URL has been attached to it? And the latest news after some URL has been attachet to it? And the conceptual mapping the definition talks about is the attachment of one or more URL's to something? – user1620696 Jan 31 '15 at 14:14
1

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:

  1. I want to read Bob's homepage
  2. I know (probably because some other web page told me) that there is a http request handler with the id /user/bob/homepage
  3. I send GET /user/bob/homepage to the web server
  4. The web server uses the id /user/bob/homepage to lookup the http request handler
  5. The web server delegates the http request to the request handler it found
  6. 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:abuse@nsa.gov

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

  1. Google: GET /user/bob/homepage
  2. Server: 200
  3. Google's 2M closest friends: GET /user/bob/homepage
  4. Server: 500

with this alternative

  1. Google: GET /user/bob/homepage
  2. Proxy: GET /user/bob/homepage
    • "I don't know what that is"
    • "And I don't know to represent it"
  3. Server: 200
  4. Proxy: 200
    • "I still don't know what that is"
    • "But now that I know how to represent it, I'll store a copy"
  5. Google's 2M closest friends: GET /user/bob/homepage
  6. 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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.