0

If I have a User entity that I want to fetch its data using two separate criteria/routes, by id and by username, what's the best practice for naming the corresponding endpoints:

GET /users/:id
GET /users/username/:username
GET /users/by-username/:username
Majed Badawi
  • 27,616
  • 4
  • 25
  • 48
  • 1
    https://stackoverflow.com/questions/20381976/rest-api-design-getting-a-resource-through-rest-with-different-parameters-but cehck it, it think it’s useful for you – Mohammad Yaser Ahmadi Jan 11 '21 at 19:00

1 Answers1

0

REST doesn't care what spelling conventions you use for your resource identifiers.

For a REST component, an identifier is semantically opaque. In other words, this is a perfectly satisfactory identifier:

/ef020224-b6f6-4c8b-92cc-752cbf11e410

It's closely analogous to a variable name in code; your compiler/interpreter doesn't care what spelling you use (subject to certain purely mechanical considerations, like which symbols are allowed as the first character in the variable name).

So all you really need to do is ensure that the identifier is consistent with your local spelling conventions.

Local spelling conventions are normally chosen to support human beings in some context. For instance, you might choose identifiers that are easy to document. Or identifiers that make pouring through HTTP access logs easier. Or whatever. The fact that the machines don't care gives you liberty to make things nicer for the humans that interact with the design.

given that I need to name two similar routes for getting the same data using two separate inputs, what's the standard that would be suitable to show the functionality of each

There isn't a "standard", in any meaningful sense.

/red/:id
/blue/:username
/green/:username

Those are all "fine".

/user-by-id/:id
/user-by-username/:username

Still fine

/user/id=:id
/user/username=:username

Still fine; it would probably look more familiar if it were in the query part

/user?id=:id
/user?username=:username

reading the first route I should understand "Gets user data from the id" and from the second "Gets user data from the username"

Something to consider: resources are generalizations of documents. The URI identifies the document, not where the document comes from or what you do to create it. Don't confuse the identify of the document with the details of fetching it.

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • thanks for the explanation. I understand that I have the flexibility of naming, but given that I need to name two similar routes for getting the same data using two separate inputs, what's the standard that would be suitable to show the functionality of each, i.e., when reading the first route I should understand "Gets user data from the id" and from the second "Gets user data from the username". My goal here is to have a well documented and readable solution. – Majed Badawi Jan 11 '21 at 18:17
  • I know that all are fine. But my question was about the most readable way – Majed Badawi Jan 12 '21 at 07:24