Question

What is a correct rest way of getting a resource ID by a field, for example a name. Take a look at the following operations:

GET /users/mike-thomas
GET /users/rick-astley

I don’t want to use these operations at my API end, instead I want to write an API operation that will get me the ID when submitting a field (name in the case of users) for example:

GET /users/id-by-field

Submitted data:

{
  "fullName": "Mike Thomas"
}

Return data:

{
  "data": {
    "id": "123456789012345678901234"
  }
}

Answer 1

What you want is known as an algorithmic URL where the parameters for the algorithm are passed as URL parameters:

GET /users?name="Mike Thomas"

Advantages are that you are using the “root” resource (users) and the search parameters are easily extended without having to change anything in the routing. For example:

GET /users?text="Mike"&year=1962&gender=M

where text would be searched for in more than just the name.

The resultant data would be a list of users and could return more than the identification of those users. Unless fullName uniquely identifies users, that is what you need to allow for anyway. And of course the list could contain a single user if the parameters uniquely identified that user.

{
  users: [
    {
      id: "123456789012345678901234",
      fullName: "Mike Thomas",
      dateJoined: 19620228
    }
  , {
      id: "234567890123456789012345"
      fullName: "Rick Astley",
      dateJoined: 19620227
    }
  ]
}