Supporting searches in Rest APIs
To use query parameters or not that is the question.
Consider this post from StackOverflow Notice that the first 2 answers identify two different approaches (nested url or query parameters) and support in the community is practically evenly split (22 vs 21).
Google web services such as search make extensive use of query parameters. But I do note Google search is an algorithm which has to accommodate a large range of queries.
Urls generally look and work (e.g. easier to remember, caching etc) better than query parameters but there is a point at which you get deeper and deeper into nested paths that it stops making sense and/OR search combinations become too complicated. At that point it makes sense to use query parameters.
I refer to this book and quote: "Query variables are perfectly acceptable for naming algorithmic resources" The author makes the case for uris but explains there's also a place for query parameters, especially for algorithmic resources such as searches.
I also think an important checkpoint is to first ensure you have first identified the resources and their uris, after that if the search can be said to be querying attributes of the resource then it may be a good candidate for using query parameters (depending on complexity).
For my particular app I could go either way:
/assets/state/pending
/assets/state/pending/userId/12345
/assets/saleId/998877A
/assets/note/mrs+brown
OR
/assets/search?state=pending¬e=mrs+brown&saleId=998877A
I prefer not to use query params and can support current requirements without query params, but I also think additional search requirements could be added to increase search complexity over time. Thus making uris more and more complicated/nested. Query params are more flexible in that regard.
Note also for multi values, commas and semi colons can be used as part of the query search e.g. /cars/colors/red,blue,green
The author of Restful web Service would recommend this last uri should use semi-colons not commas since I understand the order of colors makes no difference to the results. The author advised: Use commas if order is important, otherwise semi-colons. A useful convention perhaps.
Consider this post from StackOverflow Notice that the first 2 answers identify two different approaches (nested url or query parameters) and support in the community is practically evenly split (22 vs 21).
Google web services such as search make extensive use of query parameters. But I do note Google search is an algorithm which has to accommodate a large range of queries.
Urls generally look and work (e.g. easier to remember, caching etc) better than query parameters but there is a point at which you get deeper and deeper into nested paths that it stops making sense and/OR search combinations become too complicated. At that point it makes sense to use query parameters.
I refer to this book and quote: "Query variables are perfectly acceptable for naming algorithmic resources" The author makes the case for uris but explains there's also a place for query parameters, especially for algorithmic resources such as searches.
I also think an important checkpoint is to first ensure you have first identified the resources and their uris, after that if the search can be said to be querying attributes of the resource then it may be a good candidate for using query parameters (depending on complexity).
For my particular app I could go either way:
/assets/state/pending
/assets/state/pending/userId/12345
/assets/saleId/998877A
/assets/note/mrs+brown
OR
/assets/search?state=pending¬e=mrs+brown&saleId=998877A
I prefer not to use query params and can support current requirements without query params, but I also think additional search requirements could be added to increase search complexity over time. Thus making uris more and more complicated/nested. Query params are more flexible in that regard.
Note also for multi values, commas and semi colons can be used as part of the query search e.g. /cars/colors/red,blue,green
The author of Restful web Service would recommend this last uri should use semi-colons not commas since I understand the order of colors makes no difference to the results. The author advised: Use commas if order is important, otherwise semi-colons. A useful convention perhaps.
Comments
Post a Comment