RESTful endpoints for returning same model based on different fields?

Question

What is the recommended convention to be followed for identifying different GET endpoints that fetch the same model/entity using different fields/parameters?

For example, there is a Student entity for which I wish to expose different GET endpoints. Suppose the first GET endpoint is a get-by-id endpoint that fetches Student based on the provided ID. Another endpoint might involve fetching Student based on, say, email, yet another endpoint could be for fetching Student by phone.

I have a couple of possible approaches for designing their endpoints

1. Use separate endpoints /students/get-by-id/{id}, /students/get-by-email/{email} and /students/get-by-phone/{phone}
2. Use a single endpoint /students and accept request parameters like /students?phone=123 and then in the backend resolve which method must be used for fetching.

What is the recommended method for this?

Answer 1

The latter is more flexible. And it can search based on multiple criteria.

Answer 2

It's irrelevant, REST doesn't care either way.

What REST does care about, is that those endpoints should not be known to the client, rather the server should provide a "search page" with forms, where the client can enter search criteria, and submit it to whatever URIs are given in the form.

Do you type in the query endpoint URI for google with your search criteria already appended into your browser, or do you just use the form provided on the search page? It is the exact same thing, just pretend a human is going to use your API and design accordingly.

Answer 3

Option number 2 is probably the correct one when you are searching by telephone. Theoretically two users can share a telephone so this is not a unique identification, but you should keep in mind the following:

• Path parameter is usualy used when the criteria is uniquely identifying the record - GET /Users/{userID}
• Query parameter is used when you define a search criteria that may or may not return a result. The search crteria can be complex including several fields.