REST API Best practice: How to accept as input a list of parameter values
- by whatupwilly
Hi All,
We are launching a new REST API and I wanted some community input on best practices around how we should have input parameters formatted:
Right now, our API is very JSON-centric (only returns JSON). The debate of whether we want/need to return XML is a separate issue.
As our API output is JSON centric, we have been going down a path where our inputs are a bit JSON centric and I've been thinking that may be convenient for some but weird in general.
For example, to get a few product details where multiple products can be pulled at once we currently have:
http://our.api.com/Product?id=["101404","7267261"]
Should we simplify this as:
http://our.api.com/Product?id=101404,7267261
Or is having JSON input handy? More of a pain?
We may want to accept both styles but does that flexibility actually cause more confusion and head aches (maintainability, documentation, etc.)?
A more complex case is when we want to offer more complex inputs. For example, if we want to allow multiple filters on search:
http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}
We don't necessarily want to put the filter types (e.g. productType and color) as request names like this:
http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"]
Because we wanted to group all filter input together.
In the end, does this really matter? It may be likely that there are so many JSON utils out there that the input type just doesn't matter that much.
I know our javascript clients making AJAX calls to the API may appreciate the JSON inputs to make their life easier.
Thanks,
Will
