CODEWITHSUNDEEP
c#asp.net-web-api
user9393635
user9393635

Reputation: 1429

is it a common pattern to design a rest api search without a single item lookup uri?

A common REST API pattern is to define a single item lookup from a collection like this:

//get user with id 123
GET /users/123

Another common REST API pattern is to define a search using a POST + body like this:

POST /users/
{
   FirstName:"John",
   LastName:"Smith"
}

For the sake of consolidation, development, maintenance and support throughput, how common is it to implement all lookups through a single search like this?:

POST /users/
{
   Id:123
   FirstName:"John",
   LastName:"Smith"
}

It seems like if an org is trying to maximize development throughput and minimize maintenance and support overhead then consolidating the API call like this appears to be a reasonable solution. How common is it for developers to implement this type of pattern these days?

Upvotes: 0

Views: 258

Answers (2)

Alan
Alan

Reputation: 46883

This isn't a great question for SO, given that it's primarily opinion based.

It seems like if an org is trying to maximize development throughput and minimize maintenance and support overhead then consolidating the API call like this appears to be a reasonable solution.

Which is better, your opinion above, or the single responsibility principle.

Presumably, if you given a resource ID, the underlying implementation can efficiently look it up.

Search, assumes a search like implementation--that is, searching for a resource given a set of parameters. This can be efficient or inefficient depending on it's underlying implementation.

If you were to implement a single API call that has different behavior depending on it's arguments, you end up with more complex implementation, which is harder to test, which may make that implementation more error prone.

With an API design that alters the control flow based on the presence of inputs--it opens up design choices around whether it's an error if both sets of inputs are provided, or whether one set takes priority over another set. Further in a priority case, if one set produces no results, do you fall back to the other set?

Often in design, the simpler the implementation the more easily it's functionality is to reason about.

Thinking about the principle of least surprise, an API that better conforms to convention would be easier conceptually to understand than one that does not. While that isn't a strong argument in and of itself, there is merit to having an API that can be used in a fashion similar to other popular REST APIs.

As a consumer of your API, when should I use the ID and when should I use search? Contrast that with an API that shows very clearly, that if I have and ID I can use that ID to retrieve a resource, AND if I don't I can use Search to find that resource.

Also food for thought, why implement search as a POST, and not a GET with query strings parameters?

Upvotes: 1

discy
discy

Reputation: 430

In my opinion:

  • If one variable (like an id) is enough. Use the first.
  • If you need more info use the second.

The third makes no sense to me because if you have the ID, you don't need to provide anything else; so why should I bother the client (or myself if I put myself in his/her position) to bother with to set-up the object structure.

I think this is related to test-driven development. Make it yourself (and others, who will use your API) as clear and easy as possible.

Upvotes: 0

Related Questions