CODEWITHSUNDEEP
restapi-design
Tiago Aleff da Silva
Tiago Aleff da Silva

Reputation: 41

REST API Design Guideline. Custom identifier vs canonical identifier

I have a doubt about the guideline about custom identifier. In my case I have the following example:

1: GET /api/students => return a collection of students. (it's ok)

2: GET /api/students/{id} => return a specific student. (it's ok too)

But I have screen where the user need inform a friendly property unique for each student and I don't know how to name this route. I don't like of idea of use the 3.a:

3.a: GET /api/students/find-by-custom-property/{customId} => It seams wrong.

or

3.b: GET /api/students/custom-property/{customId} => It seams better than 3.a

Maybe need I use the case 1?

GET /api/students?customId=test => But I think that here don't make sence because this api will return a collection and don't a specific data.

What do you guys think?

Upvotes: 0

Views: 211

Answers (1)

inf3rno
inf3rno

Reputation: 26139

Well if you follow the URI RFC, then you use the query string for queries. Normally a query returns a bunch of results, not a single one, so it is absolutely normal to expect a collection.

The path component contains data, usually organized in hierarchical form, that, along with data in the non-hierarchical query component (Section 3.4), serves to identify a resource within the scope of the URI's scheme and naming authority (if any).

https://datatracker.ietf.org/doc/html/rfc3986#section-3.3

In this case we can call it hierarchical, but it is a lot simpler to add a /blah?q={some.json} than having a seprate URI template for each type of queries.

If you insist, I would do /api/students/with-custom-property/{customId}.

Upvotes: 1

Related Questions