Requiring query field to not be empty on search api

Question

we have a RESTful API that includes an endpoint for search

apiserver/v5/search?q=[search text]

for any query, it passes it off to solr and returns the result like

{code:200,results:[{..},{...}]}

if q parameter is omitted, it returns:

{code:412,message:"parameter q is required"}

if q parameter is EMPTY, eg ?q= then it also returns 412: if q parameter is omitted, it returns:

{code:412,message:"parameter q is empty"}

The design is the the search PAGE with eg example.com/search?q= will show a default view and not make the query if it is empty, but instead just show a search box or default information.

My question is, Is it poor design or very non-standard to have the API return error on empty query? ie, does it make the API very unexpected/uncomfortable, or is it quite reasonable, to enforce that "you won't get results so you should be handling this in front end behavior"

Below is the relevant code.

NOTE: search function handles all the validation and sanitation and other stuff and is outside the scope of the relevant code and question

<?php
require('search.php');

if(!isset($_GET['q'])
 echo '{"code":412,"message":"parameter q is required"}';

// should we do this to enforce they should handle front end?
if(empty($_GET['q']))
 echo '{"code":412,"message":"parameter q is empty"}';

echo search($_GET['q']);

Answer 1

do search api endpoints typically allow you to search for nothing and just return empty

It is up to the implementors (and perhaps influenced by the stakeholders) of the API. Of the APIs I’ve looked at many disallow searching without a query/keyword. Below are a few examples:

• accuweather location autocomplete
• owler company /basicsearch

does it make the API very unexpected/uncomfortable, or is it quite reasonable, to enforce that "you won't get results so you should be handling this in front end behavior"

It is quite reasonable. For a REST API "meaningful HTTP status codes are a must". If there is a front-end then it should ensure that the request is well-formed - i.e. has all required parameters.

Take for example the StackExchange API endpoint /search. If the query is missing either the tagged or intitle parameter it will return the following response:

{
  "error_id": 400,
  "error_message": "one of tagged or intitle must be set",
  "error_name": "bad_parameter"
}

And note that the response has HTTP status 400:

HTTP status 412 Precondition Failed likely isn't the best code to be used in such a case.

The HyperText Transfer Protocol (HTTP) 412 Precondition Failed client error response code indicates that access to the target resource has been denied. This happens with conditional requests on methods other than GET or HEAD when the condition defined by the If-Unmodified-Since or If-None-Match headers is not fulfilled. In that case, the request, usually an upload or a modification of a resource, cannot be made and this error response is sent back.

(emphasis: mine)

400 Bad Request would likely be more appropriate. If a form was submitted incorrectly then 422 Unprocessable Entity could be used but that might likely be more appropriate for a POST request.

The status code can be set with an HTTP header using header() and the response_code parameter

header('Content-Type: application/json', true, 400); 

If the response is JSON then it would be appropriate to set the Content-Type header to application/json - as is done in the example line above.

Answer 2

Yes, it is absolutely ok to return error in case of empty search phrase.

Returning empty set does not make much sense to me. If it were to be a success response, I'd rather expect first "default limit" items to be returned, that all match the condition of containing an empty string - which is basically equivalent to no condition at all.

As for your code, the q parameter can come also as an array. You should check not just that it is not empty, but also that it is a string.

For the response, if that's supposed to be formatted as JSON, then use proper a JSON serialization method

json_encode(['code' => 400, 'message' => '...']);

Your response

{code:412,message:"parameter q is empty"}

is actually not valid JSON, though it may be a valid javascript fragment. But in JSON, property names (code,message) must be also quoted.

I changed the code to 400, as 412 is really not much appropriate. And this should be returned as the HTTP status code rather then part of the response body. But these were already pointed out by Sam.