Search code examples
ruby-on-railsjsonapi-designjson-api

API design - json_api best practice to return no data

I have Rails app that also has an API. I've been trying to follow http://jsonapi.org for the overall structure, but I can't find any guidelines for when it comes to result without any data. I for example have an endpoint that looks like this:

https://[root]/api/apps/34/localized_strings?from_date=1330776000

Where from_date is a unix timestamp, if the server have updated or newer data based on this date value I return all the data, it there a no updates I want to return no data. And I wonder what's the best way for doing this is. The current result looks like this:

{
  "data": []
}

Would it be better or more conventional based on http://jsonapi.org to instead return a status of "status": 204 in cases where there are no changes or data?

Solution

  • According to the specification, a response representing an empty collection would be:

    HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles"
  },
  "data": []
}

    A server MUST respond to a successful request to fetch an individual resource with a resource object or null provided as the response document’s primary data.

    HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1/author"
  },
  "data": null
}