JSON format

[jasonlewis]

I'd like to hear some feedback and discuss how the JSON should be formatted. I'd like to follow the JSON API spec.

There's a few things I'm not to sure about it.

Documents that represent singular resources are wrapped inside an array and keyed by the plural form of the resource type.

I don't particulary like this. Singular resources (IMO) should be keyed by the singular form of the resource type and not wrapped inside an array. The spec recommends this:

{
  "posts": [{
    "id": 1
    // an individual post document
  }]
}

I, personally, prefer this:

{
  "post": {
    "id": 1
    // an individual post document
  }
}

I'm thinking of allowing the way responses are handled configurable, so you can easily write your own adapter.

[terion-name]

The first variant is preferable because in second variant a client should check every time was there an array or an object. It is annoying and makes client code more complicated, also produces more places where it is easy to make an error.

[jasonlewis]

True. However, my counter-argument would be: shouldn't the client know that it's requesting either a single resource or many resources (an array)?

[terion-name]

Oh, wait... I thought that it is about when you in both cases getting resource (/api/posts) and in first case there only one result is returned.
In my opinion if you request a collection (/api/posts), no matter how many results there are, an array should be returned.
When a single item is requested (/api/posts/1) — on object should be returned, there is no sense in wrapping it in array.

Additionally, I don't understand, for what is plural form of the resource type is used. If I request /api/posts I know that in result I will have posts, I don't need the posts keyword in answer. And for developing a wrapper client api library it would be more convenient to wrap all answers in simple data key, so client library can always look for data key, not for every time different.

[jgoux]

I agree with @terion-name , it seems weird to me to add a "posts" key to describe the resource, IMO the resource is described by its URL.
I would go to the generic "data" wrapper too.

[jasonlewis]

The reason the resource type is keyed is because you shouldn't really be polluting the top-level with a result. This is to allow the other top-level keys of links and meta. Although currently these aren't able to be used with Eloquent and would need to be done manually.

[terion-name]

@jgoux @jasonlewis after brief discussion in local php-community we concluded that there are several important things, why resources should be really keyed with their type name. And most rest-clients (such as ember.js) are by default tuned for this approach.

[rtablada]

If a collection, I think plural with an array (even if only one result is returned). But if it is a single object model, then singular is the way to go.

[jasonlewis]

I've documented custom response formats in the Wiki.