Send one of multiple parameters to REST API and use it

Question

I use MEAN stack to develop an application. I'm trying to develop a restful API to get users by first name or lastname
Should I write one get function to get the users for both firstname and lastname?
What is the best practice to write the URL to be handled by the backend?
Should I use the following? To get user by firstname: localhost:3000/users?firstname=Joe
To get user by name:localhost:3000/users?firstname=Terry
And then check what is the parameter in my code and proceed.

In other words,What is the best practice if I want to pass one of multiple parameters to restful API and search by only one parameter?
Should I use content-location header?

Answer 1

There is no single best practice. There are lots of different ways to design a REST interface. You can use a scheme that is primarily path based such as:

http://myserver.com/query/users?firstname=Joe

Or primarily query parameter based:

http://myserver.com/query?type=users&firstname=Joe

Or, even entirely path based:

http://myserver.com/query/users/firstname/Joe

Only the last scheme dictates that only one search criteria can be passed, but this is likely also a limiting aspect of this scheme because if you, at some time in the future, want to be able to search on more than one parameter, you'd probably need to redesign.

In general, you want to take into account these considerations:

1. Make a list of all the things you think your REST API will want to do now and possibly in the future.
2. Design a scheme that anticipates all the things in your above list and feels extensible (you could easily add more things on to it without having to redesign anything).
3. Design a scheme that feels consistent for all of the different things a client will do with it. For example, there should be a consistent use of path and query parameters. You don't want some parts of your API using exclusively path segments and another part looking like a completely different design that uses only query parameters. An appropriate mix of the two is often the cleanest design.
4. Pick a design that "makes sense" to people who don't know your functionality. It should read logically and with a good REST API, the URL is often fairly self describing.

So, we can't really make a concrete recommendation on your one URL because it really needs to be considered in the totality of your whole API.

Of the three examples above, without knowing anything more about the rest of what you're trying to do, I like the first one because it puts what feels to me like the action into the path /query/users and then puts the parameters to that action into the query string and is easily extensible to add more arguments to the query. And, it reads very clearly.

There are clearly many different ways to successfully design and structure a REST API so there is no single best practice.