Hello.

Recenty merged pull request #341 contains breaking changes to the previous JSON API resource structure. It actually not the resource anymore, but data. Everything is a data now.

And I completely disagree with that. I believe there are other people who thinks differently that PR author.
Previous version was online for quite a long time, and it was adopted and loved for it old structure. Don't rush for irreversible changes and lock the 1.0. Listen to other people before changing the standard.

Now, lets get closer to what I am disagree with exactly.
It is the data root namespace and required type key.
Don't let the bad code practices fool you. It is absolutely not needed and adds more problems that it could possibly solve (if any):

Naming.

"data" keyword means nothing. Server returns a set or unknown things. Query the /videos enpoint and get some unknown data objects that could be identified only by the type key.

Linked objects. ungrouped and comes in a mess:

"linked": [{
    "type": "people",
    "id": "9",
    "first-name": "Dan",
    "last-name": "Gebhardt",
    "twitter": "dgeb",
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "body": "First!",
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "body": "I like XML better",
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]

Clients are forced to go item by item to build required collection (comments or people).

Pseudo help for sti.

Don't leak your DB structure to the API!

If response should contain objects of the different type, don't return unnamed data mess.
return the "covers" or "thumbnails" instead:

{
  "thumbnails": [
    {
      "id": "laonet",
      "title": "LAO NET TV",
      "cover_image": {
        "sd": "http://example.com/sd.jpg",
        "hd": "http://example.com/hd.jpg"
      },
      "href": "http://example.com/channels/laonet",
      "type": "channel"
    },
    {
      "id": "dexter",
      "title": "Dexter",
       "cover_image": {
        "sd": "http://example.com/sd.jpg",
        "hd": "http://example.com/hd.jpg"
      },
      "href": "http://example.com/shows/dexter",
      "type": "show"
    },
}

Resource Data creation.

POST /photos

{
  "data": {
    "type": "photos",
    "title": "Ember Hamster",
    "src": "http://example.com/images/productivity.png"
  }
}

What? This explicitly says that /photos endpoint can create any resources.
This call does not create a resource, it create some abstract "data mess".
Compare:

POST /photos

{
  "photos": {
    "title": "Ember Hamster",
    "src": "http://example.com/images/productivity.png"
  }
}

If in doubt, try to think why this API uses JSON but not the XML. The last one has more adaptive structure, can have attributes and other bells and whistles. But for some reason people pick JSON, guess why?

Thank you for your time.
To be continued