Should return empty array of verses when none matching found

[raysarebest]

Currently, when no passages match a specific tag, the API returns HTTP 204 No Content. From a front-ender's perspective, this is somewhat counterintuitive and harder to handle. When no verses are found to match, the API should return an empty array, so extra front-end code does not have to be written to handle the case when none match. Take this theoretical JavaScript code, for example, which is written to handle the current scenario:

getData((response, error) => {
    if(response.statusCode === 200 && !error){
        for(let verse of response.verses){
            tellUser(verse.text);
        }
    }
    else if(response.statusCode === 204){
        tellUser("Sorry, but no verses were found for that tag");
    }
    else if(error){
        // Inspect and handle the error case here
    }
});

That's a lot of extra boilerplate code that doesn't have to be written, and it should really be lumped into the error object, but it's not by default. A cleaner way to do that would be to just write the code to iterate over an array, and the case when no verses are returned will handle itself, like this:

getData((response, error) => {
    if(!error){
        for(let verse in responses.verses){
            tellUser(verse.text);
        }
    }
    else{
        // Handle the error case
    }
});

That alone shaved off 3 lines of code and one conditional statement that might not be so obvious to newcomers.

On top of that, a lot of frameworks, such as the one I initially used to build the Slackbot, don't allow direct access to the status code of the response, thus making it impossible to effectively handle this case without crashing.

That being said, I don't think we should get rid of 204 No Content altogether. I think it would make the most sense to return an empty array in the case that there are no verses found, thus you can unconditionally check response.verses for all your results, but I think the API should return 204 No Content when it's asked about an invalid verse, like Book 5:17 or Genesis 578:3252. Thus, the 204 No Content response can signify where there will forever truly be no content, instead of content just hasn't been added yet