We're designing a rest endpoint for retreiving name autocompletion suggestions for hotel names.
Currently it's defined like this: GET /suggest/:term, so that if you queried `/suggest/hil' you would get responses like "Hilton Paris", "Hilton New York", etc.
One of our colleagues argues that this is against REST API design best practices, and that the search term should instead be a query parameter, i.e. /suggest?term=hilt.
Looking around other famous APIs, it seems that they all use a query parameter:
- https://developers.google.com/places/webservice/autocomplete
- https://swiftype.com/documentation/autocomplete
but I'd like to know why; whether the former is actually bad design and what guidelines would get me to make it a query parameter in the first place.
Best Answer
REST services are typically focused on resources, with the path separator (forward slash) denoting sub-resources in a hierarchy. Resources are typically things ("nouns" in English) rather than actions ("verbs" in English).
To conform to this style, your "suggest" endpoint (a verb) could be named "suggestions" (a noun) because it provides access to suggestions. Just as an example, a sub-resource for suggestions might be individual suggestions with URLs like
/suggest/Hilton%20New%20Yorkwhere the response could be a link to the actual "Hilton New York" hotel resource.Actions like "suggest" are typically represented through HTTP verbs, e.g.
GET /suggestions/.Your "term" is essentially a filter, which are typically passed through query parameters or in the request body. A more robust implementation is described in this SO answer.