RESTful API - Optional parameters and overloading vs. multiple routes

Question

I have a REST API resource that can be fetched using one of multiple identifiers. Sometimes a client might want a specific resource, and sometimes they might want a set of resources based on a certain field.

For an easy example, let's say some clients store a resourceId and other clients store a resourceNumber. In addition, a client might want to fetch all resources where resourceCategory equals a specific value.

There are several approaches I can take to implement this, and I would like to know if there is a best practice or one approach is preferred.

1. Have a single route such as GET /api/resource with parameters for resourceId, resourceNumber and resourceCategory. Based on the parameters provided, return the corresponding resource(s).

2. Have multiple routes such as

   • GET /api/resource/id/{resourceId}
   • GET /api/resource/number/{resourceNumber}
   • GET /api/resource/category/{resourceCategory}.

Approach #1 allows someone to specify multiple options, which in some cases could be good but in other cases doesn't make sense (i.e. a resourceId and resourceNumber could be mutually exclusive)

I have done a lot of googling and researched the OpenAPI spec (which I am following), but have failed to find anything that addresses this issue.

Please Note!!! I am not looking for individual opinions. I want to follow any best practices / standards that exist, so I am asking if there is a best practice or standard such as OpenAPI that covers this scenario for RESTful web services.

I am also curious as to which approach is more commonly used, although I realize this can be difficult to determine.

Answer 1

I am asking if there is a best practice or standard such as OpenAPI that covers this scenario for RESTful web services.

REST isn't going to offer you much guidance here.

The issue is this: choosing a design for your controllers is an implementation detail. The point of REST is that those implementation details are hidden behind the uniform interface.

In other words, your RESTful web service should behave like a web site, or an HTTP cache. The resource identifiers are just keys used to look up representations in the cache.

/api/resource?resourceId={resourceId}
/api/resource?resourceNumber={resourceNumber}

As far as REST is concerned, these are different resources. There's no particular reason to assume that they are related to each other. The client won't assume that changes to one necessarily imply changes to the other.

Semantically, the identifier is just an identifier, like a surrogate key in a database or a UUID. REST clients don't try to extract meaning from the identifier.

REST clients do understand the rules for relative references, because they are described by RFC 3986. So you might make choices about different spellings of identifiers based on how dot-segments are processed (path segments and the query being handled differently).

Certain URI spellings are easier to work with because they align with a URI template implementation that you have available to you. URI Templates make it easier to inject information into an identifier, or extract it later; and the patterns are standardized.

But the patterns are still semantically agnostic.

Twenty years ago, one of the things we needed to worry about was implementations that failed to conform to the standards, and so you might choose your identifier spellings to avoid problem areas. But again - its a semantically agnostic concern.

So all that's really left is a bunch of spelling conventions for humans, and just like variable names, the arguments are largely political concerns in the local context (ie: your spellings should be "consistent" with those chosen by the programmer sitting at the next desk.)