REST API url convension for filtering resources with different criterias - naming

Question

I have a REST API to expose a resource, Employee with the following fields(id, firstName, LastName, Age, Salary). (Please note that this is a sample resource and my actual resource is more complex) This is an ASP.Net WEB API which serves to an Angular front end.
Few of my current REST API endpoints are as follows
HTTP GET (Get all the employees) api/employees
HTTP GET (Get a single employee by id) api/employees/{id}
PUT , POST and DELETE are following the normal REST standard
Now I have few different filtering requirements like Get all emloyees by FirstName, Get all Employees by Last Name, Get all employees who's salary is greater than 1000
in an RPC setup I would create methods like
GetEmployeesByFirstName('donald')
GetEmployeesByLastName('trump')
GetEmployeesBySalaryGreaterThan(1000)
and achieve this.
But I am a bit confused on how to design these URLs according to the REST API standards.
I thought of doing like below but I feel these are also not conforming to the REST standard (as I understand it)
api/employees/get-by-firstname?firstName=donald OR api/employees/by-firstname?firstName=donald
api/employees/get-by-lastname?lastName=trump OR api/employees/by-lastname?lastName=trump
api/employees/get-salary-greterthan?salary=1000 OR api/employees/salary-greterthan?salary=1000
I really think the URLs should be like
api/employees?firstName=donald
api/employees?lastName=trump
api/employees?salary=1000(hmm not sure about this one)
But I am having issues creating my ASP.Net Web API controller as the route is almost the same api/employees and it gives me exceptions
The project I am working on has some rules saying that we have to follow the REST standard when creating APIs. Can someone help me on how I should design my URLs in this kind of filtering situations

Answer 1

If you are querying employees then the following URLs should all hit the same action method
api/employees?firstName=donald
api/employees?lastName=trump
api/employees?salary=1000
To do this you should create an object that will capture the possible parameters:
public class EmployeeFilterParams{
public string firstName { get; set; }
public string lastName { get; set; }
public string salary { get; set; }
}
and then create the action in the Employees controller:
[HttpGet]
public ActionResult Get(EmployeeFilterParams params){
if (!string.IsNullOrEmpty(params.firstName)){
// do something here for firstName
}
... repeat for each parameter
}
Because this is a GET request ASP.Net's default model binding should populate the properties in params (EmployeeFilterParams).
This method has the added benefit that you can easily filter on multiple parameters i.e.
api/employees?firstName=donald&lastName=trump&salary=1000
THIS CODE IS UNTESTED BUT SHOULD GIVE YOU A GOOD STARTING POINT

Answer 2

I am a bit confused on how to design these URLs according to the REST API standards.
REST doesn't care what spelling conventions you use for your URLs. As far as a consumer is concerned, they are opaque identifiers. Any information encoded into the identifier is done at the server's discretion and for its own convenience.
Which is good in that it means that you, the server, can choose identifier spellings that work with whatever local routing library you happen to be using. So you can choose any spelling that makes ASP.Net Web API Controller easy to work with, and that's fine.
/api/employees/get-salary-greterthan?salary=1000
/api/employees/salary-greterthan?salary=1000
/api/employees?salary=100
/api/reports/employees-by-salary?greaterThan=1000
/api/reports/employees-by-salary/greaterThan/1000
/api/9048aa3e-9058-4248-8949-459bb4a02019
Those are all fine.
Identifiers that use key/value pairs in the query are convenient when you are using HTML to interact with your API, because the HTML forms can be used as a sort of URI template. If you are targeting clients with more sophisticated template capabilities, then you have more freedom about how you encode the information into the URI.
I have seen in most of the documents which explains REST url naming convensions saying that we should not use VERBs in the url (like "get" in the get-salary-greterthan part of the url).
https://www.merriam-webster.com/dictionary/put
https://www.merriam-webster.com/dictionary/post
https://www.merriam-webster.com/dictionary/patch
Notice that these URI work exactly as you would expect, even though put, post, and patch are all registered HTTP method tokens.
URI spelling conventions are analogous to spelling conventions for variable names - they are there just to make things "easy" for human beings. The machines don't care.