An API in JSON with relationships

api.md

• Get a single resource: GET /posts/1

{
  "id": 1,
  "body": "...",
  "author": {
    "id": 2,
    "name": "Lucy",
    "_links": { "self": "/authors/2" }
  },
  "_links": {
    "self": "/posts/1",
    "author": "/authors/2",
    "comments": "/posts/1/comments"  // or "/posts/1/comments/3,4" (?)
  }
}

• Get a collection: GET /posts/1/comments

{
  "comments": [
    {
      "id": 3,
      "body": "...",
      "author": {
        "id": 5,
        "name": "John",
        "_links": { "self": "/authors/5" }
      },
      "_links": {
        "self": "/comments/3",
        "author": "/authors/5"
      }
    },
    {
      "id": 4,
      "body": "...",
      "author": {
        "id": 2,
        "name": "Lucy",
        "_links": { "self": "/authors/2" }
      },
      "_links": {
        "self": "/comments/4",
        "author": "/authors/2"
      }
    }
  ],
  "_links": {
    "self": "/posts/1/comments",
    "more": "/posts/1/comments?since=4",
    "authors": "/authors/2,5"
  }
}

• Get a list of resources by id: GET /authors/2,5

{
  "authors": [
    {
      "id": 2,
      "name": "Lucy",
      "_links": { "self": "/authors/2" }
    },
    {
      "id": 5,
      "name": "John",
      "_links": { "self": "/authors/5" }
    }
  ],
  "_links": { "self": "/authors/2,5" }
}

• Create a resource (and link it to a parent): POST /posts/1/comments

{
  "body": "..."
}

• Create many resources: POST /posts

[
  {
    "body": "..."
  },
  {
    "body": "..."
  }
]

• Update a resource: PUT /comments/4

{
  "body": "..."
}

• Delete a resource: DELETE /comments/4
• Remove a link between 2 resources: DELETE /comments/4/authors/2