

JSON-API, a specification for API behavior, goes 1.0 - mixonic
https://github.com/json-api/json-api/pull/727

======
keithwhor

        For example, a GET request to a URL from a to-one relationship link could return: [...]
        If the above relationship is empty, then a GET request to the same URL would return: [...]
        A GET request to a URL from a to-many relationship link could return: [...]
    

In each of these cases, the "data" attribute can hold three different data
types. An array, null, or a single object.

But then, _data_ doesn't even have to be present (and indeed, MUST NOT be) if
errors is present. So now we have four different data types. [], null, {}, or
undefined.

If this is supposed to be a _standard_ , why not standardize your data
property? An array works as a data type for each of these (normal, empty, only
one item) and you can then _always_ require a data field in the response
instead of "only data or errors may be returned"? The most important part of
building an API standard isn't the standard itself, it's anticipating the
_tooling_ you use to parse it.

By having only _errors_ or _data_ present on a response you immediately create
two possible ways developers can create an interface for an API using this
standard:

    
    
        if (response.errors) { /* there was an error */ }
    

OR

    
    
        if (response.data) { /* there were no errors */ }
    

But what if data is null?

    
    
        if (response.hasOwnProperty(data)) { /* there were no errors */ }
    

The first method is _clearly_ preferred, so why do we care what _data_ looks
like, anyway? Why not make it always an array? Things like this:

    
    
        if (!response.data.length) { /* do a thing */ }
    

Would be unambiguous because response.data always exists as an array that will
have a length of 0 or more.

 __tl;dr: I don 't like some part of this standard.
[http://xkcd.com/927/](http://xkcd.com/927/)

