0

REST APIS are a Uniform interface.

Is it better to add functionality to the search parameters of a GET request with a query parameter, than to add nested resource identifiers to a collection /exists or /exists/type.

Must resource identifiers have database entities unlike /exists or can they return results from domain entities that don't exist in the database or from entities which are derived from the domain model.

Is it better to hide functionality behind the correct HTTP verbs than to add extra routes. For example GET of a entity would choose the search implementation base on a query parameter

Which endpoint better conforms to this practice.

The web application is a simple collection of users

Users
----
id
name
type:enum(staff-team1,staff-team2,staff-team3,manager,director)

Normal CURD operations are needed on the Users entity and with further functionality for search like pagination search members of only a particular type search if a member of a type exists search for users who have a name start starts with {string}

From the front end I need to get if any of a given type exists. What would the best URL be to create to get this information.

/users/exists?type=staff-team1
/users/exists/type/{type}
/users/exists-type/{type}
GET /users?type=staff-team1
1
  • Please clarify your specific problem or provide additional details to highlight exactly what you need. As it's currently written, it's hard to tell exactly what you're asking.
    – Community Bot
    Commented Oct 19, 2022 at 17:04

2 Answers 2

1

What would the best URL be to create to get this information?

Trying not to be too opinions-based, RESTful semantics generally organize entities as resources and you differentiate actions against those resources using plain old HTTP verbs very similar to how simple webservers work.

As an example, you want a webpage(the resource) and so you GET /lovely-unicorn-website but perhaps you want to apply some parameters to your query - then HTTP has query parameters for that. If no resources match your query, then you get a 404 Not Found - straight forward enough!

This creates a standard that makes consuming APIs more intuitive across different vendors.

If we look at some public REST APIs as a reference:

  • See Spotify's Album API - we can GET a list of albums for a particular region using GET /albums?market=ES
  • See StackExchange's User API - we can GET a list of users with a filter by name with GET /users?inname=jeff

In your case, your resource is a User, your query parameter is the type, and the action you're performing is a GET so as a consumer, I'd expect I can get a list of users by some type using GET /user?type=staff-team1 like your last example and if the results are empty, then I'd take that as "well I guess none exist!" - similarly if looking for a specific user(rather than a listing) and I get back a 404 Not Found - that tells me plain and simple that it doesn't exist.

A lot of value that comes from following REST conventions is in the low cognitive load from consuming a new API because it's interface is a lot like other REST apis so a nice rule of thumb is to look at how other RESTful APIs do things. Looking at the above and other public APIs, I don't often see separate endpoints to check for existence. However, if reasons compel you to break these standard conventions, that's totally fine - for example, if listing users is a very expensive operation and you want to avoid having to do such an operation just to check existence. There's a lot of opinions in this space, but the best solutions are usually the ones that work.

0

There are many different opinions on this topic and I don't pretend to have the 'correct' answer. But I will offer a rule of thumb that may help you in these kinds of questions based on a high-level theory around REST.

Fundamentals: The core entity in REST is the concept of a resource. These are the 'things' in your API. For example, if API is providing access to user records, the Universal Resource Identifier (URI) for a user is how we refer to that user.

It's frowned upon by REST advocates to use verbs inside a URI. Actions/verbs are the methods e.g. GET, POST, PUT. Putting 'exists' in the URI violates that principle. If you just want to check for the existence of a resource, consider the lesser known OPTIONS and HEAD methods.

Query parameters should IMO, be used for things that are not required. Whatever is needed to refer to a unique resource should be in the URI path.

Your examples seem to suggest that you are looking for a list of users. A list of users is its own resource in REST terminology that is separate from the users in the list. If you want to filter the list of users by the query parameter (which it seems you do) then that would be appropriate. Something along the lines of the last example seems OK to me. Ideally, that would provide a response containing the direct URIs for the user resources that match the criteria.

5
  • I'm not looking for a list of users. I'm looking for, if any users exists of type. Does a manager exist? or does a staff-team1 user exist?
    – Ten Jones
    Commented Oct 19, 2022 at 19:26
  • The issue stands. If i user option or head. and query HEAD /users?searchType=type,searchValue=manager. Now I have this "choose the filter issue" in both GET and HEAD routes.
    – Ten Jones
    Commented Oct 19, 2022 at 19:28
  • @pepsi-maniac I would tend to go with returning a list of users and then checking the length. If the length of the list is non-zero, then users of that type exist. If you are worried about retrieving too much data, put count in the headers and use HEAD.
    – JimmyJames
    Commented Oct 19, 2022 at 19:31
  • @pepsi-maniac I'm not sure what the 'choose the filter issue' is exactly. type=staff-team1 seems perfectly adequate to me and allows you to use multiple conditions or different types. What problem do you see with this?
    – JimmyJames
    Commented Oct 19, 2022 at 19:33
  • Yeah, thanks. I just mean i'll probs need to create a function for this part that both endpoints (services) can use
    – Ten Jones
    Commented Oct 19, 2022 at 20:52

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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