2

I need to create a RESTful webservice that allows for addressing entities by using different types of IDs. I will give you an example based on books (which is not what I need to process but I want to build a common understanding this way).

Books can be identifier by:

  • ISBN 13
  • ID
  • title

I can create a book by POSTing to /api/v1/books/The%20Bible. This book can then later be addressed by its ISBN /api/v1/books/12312312301 or ID /api/v1/books/A9471IZ1. If I implemented it this way I would need to analyze whatever identifier gets sent and convert it internally.

Is it 'legal' to add the type of identifier to the URL ? Like /api/v1/books/title/The%20Bible?

laurent
  • 79,308
  • 64
  • 256
  • 389
Marged
  • 9,123
  • 9
  • 45
  • 87
  • It is of course `legal` you are identifying the route to handle the title, ISBN etc, nothing wrong with that. – Pogrindis Apr 28 '15 at 08:04

2 Answers2

2

It seems that what you need is not simply retrieving resources, but searching for them by certain criteria (in your case, by ISBN, title or ID). In that case, rather than complicate your /books endpoint (which, ideally, should only returns books by ID), I'd create a separate /search function. You can then use it search for books by any field.

For example, you would have:

GET /search?title=bible

GET /search?isbn=12312312301

It can even be easily expanded to add more fields later on.

laurent
  • 79,308
  • 64
  • 256
  • 389
0

First: A RESTful URl should only contain nouns and not verbs. You can find a lot of best-practices online, as example: RESTful API Design: nouns are good, verbs are bad

One approach would be to detect the id/identifier in code. The pattern would be, as you already mentioned:

GET /api/v1/books/{id}, like /api/v1/books/12312312301 or /api/v1/books/The%20Bible

Another approach, similar to this.lau_, would be with a query parameter. But I suggest to add the query parameter to the books URL (because only nouns, no verbs):

GET /api/v1/books?isbn=12312312301

The better solution? Not sure… Because you are selecting “one book by id” (except title), rather than performing a query/search, I prefer the first approach (…/books should return “a collection of books” and .../books/{id} should return only one book).

But maybe someone has a better approach/idea?

Edit: I suggest to avoid adding the identifier to the URL, it has “bad smell”. But is also a possible approach and I saw that a lot in other APIs. Let’s see if I can find some information on that, if its “ok” or should be avoided.

Edit 2: See REST API DESIGN - Getting a resource through REST with different parameters but same url pattern and REST - supporting multiple possible identifiers

Community
  • 1
  • 1
1ppCH
  • 276
  • 1
  • 3
  • 13
  • OK, I think I get the basic idea. So if I ever would need to upload a cover image for any of the books this would become a `POST` to `/api/v1/books/cover?isbn=12312312301` ? – Marged Apr 28 '15 at 08:59
  • @Marged To upload a cover to a particular book the URL would look like: `POST /api/v1/books/{id}/cover`, in your case `/api/v1/books/12312312301/cover`. – 1ppCH Apr 28 '15 at 09:57