REST API Best practice: How to accept list of parameter values as input [closed]

by

A Step Back

First and foremost, REST describes a URI as a universally unique ID. Far too many people get caught up on the structure of URIs and which URIs are more “restful” than others. This argument is as ludicrous as saying naming someone “Bob” is better than naming him “Joe” – both names get the job of “identifying a person” done. A URI is nothing more than a universally unique name.

So in REST’s eyes arguing about whether ?id=["101404","7267261"] is more restful than ?id=101404,7267261 or \Product\101404,7267261 is somewhat futile.

Now, having said that, many times how URIs are constructed can usually serve as a good indicator for other issues in a RESTful service. There are a couple of red flags in your URIs and question in general.

Suggestions

  1. Multiple URIs for the same resource and Content-Location

    We may want to accept both styles but does that flexibility actually cause more confusion and head aches (maintainability, documentation, etc.)?

    URIs identify resources. Each resource should have one canonical URI. This does not mean that you can’t have two URIs point to the same resource but there are well defined ways to go about doing it. If you do decide to use both the JSON and list based formats (or any other format) you need to decide which of these formats is the main canonical URI. All responses to other URIs that point to the same “resource” should include the Content-Location header.

    Sticking with the name analogy, having multiple URIs is like having nicknames for people. It is perfectly acceptable and often times quite handy, however if I’m using a nickname I still probably want to know their full name – the “official” way to refer to that person. This way when someone mentions someone by their full name, “Nichloas Telsa”, I know they are talking about the same person I refer to as “Nick”.

  2. “Search” in your URI

    A more complex case is when we want to offer more complex inputs. For example, if we want to allow multiple filters on search…

    A general rule of thumb of mine is, if your URI contains a verb, it may be an indication that something is off. URI’s identify a resource, however they should not indicate what we’re doing to that resource. That’s the job of HTTP or in restful terms, our “uniform interface”.

    To beat the name analogy dead, using a verb in a URI is like changing someone’s name when you want to interact with them. If I’m interacting with Bob, Bob’s name doesn’t become “BobHi” when I want to say Hi to him. Similarly, when we want to “search” Products, our URI structure shouldn’t change from “/Product/…” to “/Search/…”.

Answering Your Initial Question

  1. Regarding ["101404","7267261"] vs 101404,7267261: My suggestion here is to avoid the JSON syntax for simplicity’s sake (i.e. don’t require your users do URL encoding when you don’t really have to). It will make your API a tad more usable. Better yet, as others have recommended, go with the standard application/x-www-form-urlencoded format as it will probably be most familiar to your end users (e.g. ?id[]=101404&id[]=7267261). It may not be “pretty”, but Pretty URIs does not necessary mean Usable URIs. However, to reiterate my initial point though, ultimately when speaking about REST, it doesn’t matter. Don’t dwell too heavily on it.

  2. Your complex search URI example can be solved in very much the same way as your product example. I would recommend going the application/x-www-form-urlencoded format again as it is already a standard that many are familiar with. Also, I would recommend merging the two.

Your URI…

/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}

Your URI after being URI encoded…

/Search?term=pumas&filters=%7B%22productType%22%3A%5B%22Clothing%22%2C%22Bags%22%5D%2C%22color%22%3A%5B%22Black%22%2C%22Red%22%5D%7D

Can be transformed to…

/Product?term=pumas&productType[]=Clothing&productType[]=Bags&color[]=Black&color[]=Red

Aside from avoiding the requirement of URL encoding and making things look a bit more standard, it now homogenizes the API a bit. The user knows that if they want to retrieve a Product or List of Products (both are considered a single “resource” in RESTful terms), they are interested in /Product/... URIs.

More Related Contents:

  1. What exactly is RESTful programming?
  2. Best practices for API versioning? [closed]
  3. If REST applications are supposed to be stateless, how do you manage sessions?
  4. RESTful URL design for search
  5. Free Rest API to retrieve current datetime as string (timezone irrelevant) [closed]
  6. Design RESTful query API with a long list of query parameters [closed]
  7. HTTP response code for POST when resource already exists
  8. Security of REST authentication schemes
  9. How to make remote REST call inside Node.js? any CURL?
  10. How to understand “RESTful API is stateless”?
  11. Best practice for partial updates in a RESTful service
  12. Groovy built-in REST/HTTP client?
  13. Unable to upload zip file through karate framework
  14. API pagination best practices
  15. How to use cURL to send Cookies?
  16. Querystring in REST Resource url
  17. How to construct a REST API that takes an array of id’s for the resources
  18. Spring @ExceptionHandler does not work with @ResponseBody
  19. Why the slow WADL uptake? [closed]
  20. Azure Websites Kudu REST API – Authentication
  21. How to format Swagger 2.0 text descriptions?
  22. Update an entire resource collection in a REST way
  23. What are the best/common RESTful url verbs and actions?
  24. How should the header X-DocuSign-Authentication be used for REST and SOAP?
  25. Restful way for deleting a bunch of items
  26. When is it appropriate to respond with a HTTP 412 error?
  27. Swagger documentation with JAX-RS Jersey 2 and Grizzly
  28. How one could use server side sorting and paging with Azure Mobile Services
  29. ‘Best’ practice for restful POST response
  30. Swagger UI passing authentication token to API call in header

Leave a Comment