Rest convention: Should api send details api url for listings or clients hard code them?

Question

We have listing and details page for mobile, desktop, android and ios?

We have two apis- one for listing and other for details of those listings. So one api is assosiated with other.

listing api looks like: /api/books/?price=100-300

details api looks like: /api/book/{bookId}

listing api in response sends back details api link for each listing: For example: Request:

/api/books/?price=100-300

will have Response:

{
  "books":[
     {
       "id": 1,
       "price": 120,
       "pages": 400,
       "detailsUrl": "/api/book/{bookId}"
     }
  ]
}

The problem is, should I send detailsUrl with each listing or let all the clients create this? Since they have bookId, they can create it.

What is considered to be best practise considering the url params in details api url may get added in future, api may be versioned and all other possibilities for widely used apis?

While primarily opinion-based, This sounds similar to [Hypermedia As The Engine Of Application State](https://en.wikipedia.org/wiki/HATEOAS). You can apply a convention for your api. but make sure that proper documentation explains the concepts of the api. — Nkosi, Jan 23 '17 at 11:51

score 1 · Accepted Answer · edited May 23 '17 at 12:09

I'd put my money on creating the link.

There is a perfect explanation why putting id is not enough

DO NOT include just an entity's ID (such as 12) in a response, because that way you're forcing clients to put together resource URIs themselves. In order to do that, they would need to have prior knowledge of what URIs there are, and you're losing control over the URI space on the server side.

I recommend to read the entire, linked text (approved answer), it's very detailed and got nice resources. As the author mentioned, there is a popular convention how to make connections between resources - HAL. Consider this instead of detailsUrl.

Even if a link to the resource is obvious right now and you decided to put id alone, in other resources after some time it won't be so simple and you will be forced to specify full URL. Then your API won't be consistent. Experience has taught me it's always easier and better for maintenance to send back full link.

Rest convention: Should api send details api url for listings or clients hard code them?

1 Answers1