JSON-API, a specification for API behavior, goes 1.0

https://github.com/json-api/json-api/pull/727

by mixonic • 11 years ago

6 1 11 years ago

keithwhor• 11 years ago

    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 */ }

    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/

JSON-API, a specification for API behavior, goes 1.0

Related Stories