CODEWITHSUNDEEP
web-servicesrest
Marged
Marged

Reputation: 10973

What's the correct way to create a REST service that allows for different types of identifiers?

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:

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?

Upvotes: 2

Views: 292

Answers (2)

1ppCH
1ppCH

Reputation: 278

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

Upvotes: 0

laurent
laurent

Reputation: 90863

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.

Upvotes: 2

Related Questions