CODEWITHSUNDEEP
apiresturirestful-urlrestful-architecture
Dr. Jan-Philip Gehrcke
Dr. Jan-Philip Gehrcke

Reputation: 35826

RESTful web service: create new resource by combining other resources: provide IDs or URIs?

When obtaining a collection of items from a RESTful web service (via GET), the representation of each single item (e.g. in JSON) usually contains the item's resource identifier. This can either be the ID of the resource or the entire URI which usually contains the ID.

This identifier (ID or URI) is required in case the client needs to further interact with the remote resource representing the single item. Many people seem to consider it good practice to provide the entire URI and not only the ID, so that the client has nothing to do with URI construction (for example, this is what Miguel Grinberg writes in this article).

But what should be done in case multiple items are to be combined in order to create a new resource? Then the client needs to tell the server which items are to be combined. And eventually, the server requires a list of IDs for processing the request. Assuming that the client retrieved URIs for each item in the first place -- where would you perform the URI parsing in order to extract the raw IDs again: in the client or in the server?

Example: the client retrieved a collection of pages in a GET request. Each page item identifies itself with an URI (containing the ID):

{
  "pages": [
    {
      "content": "bla bla",
      "uri": "/pages/1"
    },
    {
      "content": "that is no interesting content",
      "uri": "/pages/2"
    },
    ...
  ]
}

Now assume that the client instructs the server to create a new resource combining multiple pages: a book, built by pages 1 and 2. The POST request body can either contain IDs or URIs:

{
  "title": "A Boring Book",
  "pages": [1, 2]
}

or

{
  "title": "A Boring Book",
  "pages": ["/pages/1", "/pages/2"]
}

In the first case, the clients needs to know the structure of the URI and extract the ID before sending the request. In the second case the server needs to extract the ID from the URI.

On the one hand, I like the idea of resources being represented on the client side by URIs only. On the other hand, I also like to keep things simple and pragmatic and why should we send entire URIs to the server when the context is clear and only the IDs are needed (the book creation does not directly act on page resources)?

What would you prefer and why? Or do you think that this is really not too important?

Do you think the following approach would be a good compromise? Client-side extraction of the ID from the URI by parsing the URI from right to left and extracting the number after the rightmost slash, i.e. assuming a certain URI structure without the need to hardcode the entire path.

Upvotes: 1

Views: 611

Answers (1)

braunpet
braunpet

Reputation: 449

I think that clients should receive absolute URLs from the server and only use these without any kind of modification. Therefore, I would even go one step further beyond your last example:

{
  "title" : "A Boring Book",
  "pages" : [ "http://.../pages/1", "http://.../pages/2" ]
}

Only the server should be responsible to extract Ids from URLs if necessary.

Upvotes: 1

Related Questions