3

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?

3 Answers 3

3

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

2

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.
1

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.