title: JSON API questions. Included vs relationships
body: <p>I am reading <a href="http://jsonapi.org/format/#document-resource-identifier-objects" rel="nofollow">this</a> before building an API endpoints. I read this quote about compound documents:</p>
  
  <blockquote>
    <p>To reduce the number of HTTP requests, servers MAY allow responses
    that include related resources along with the requested primary
    resources. Such responses are called "compound documents".</p>
  </blockquote>
  
  <p>Here is a sample JSON response using the JSON API specification:</p>
  
  <pre><code>{
    "data": [{
      "type": "articles",
      "id": "1",
      "attributes": {
        "title": "JSON API paints my bikeshed!"
      },
      "links": {
        "self": "http://example.com/articles/1"
      },
      "relationships": {
        "author": {
          "links": {
            "self": "http://example.com/articles/1/relationships/author",
            "related": "http://example.com/articles/1/author"
          },
          "data": { "type": "people", "id": "9" }
        },
        "comments": {
          "links": {
            "self": "http://example.com/articles/1/relationships/comments",
            "related": "http://example.com/articles/1/comments"
          },
          "data": [
            { "type": "comments", "id": "5" },
            { "type": "comments", "id": "12" }
          ]
        }
      }
    }],
    "included": [{
      "type": "people",
      "id": "9",
      "attributes": {
        "first-name": "Dan",
        "last-name": "Gebhardt",
        "twitter": "dgeb"
      },
      "links": {
        "self": "http://example.com/people/9"
      }
    }, {
      "type": "comments",
      "id": "5",
      "attributes": {
        "body": "First!"
      },
      "relationships": {
        "author": {
          "data": { "type": "people", "id": "2" }
        }
      },
      "links": {
        "self": "http://example.com/comments/5"
      }
    }, {
      "type": "comments",
      "id": "12",
      "attributes": {
        "body": "I like XML better"
      },
      "relationships": {
        "author": {
          "data": { "type": "people", "id": "9" }
        }
      },
      "links": {
        "self": "http://example.com/comments/12"
      }
    }]
  }
  </code></pre>
  
  <p>So from what I can see, the relationships sections give basic/sparse information about the associations between the articles table and other tables. It looks like an article belongs_to an author and has_many comments.</p>
  
  <p>What will the links be used for? Will the API have to use the link in order to receive more detailed JSON about the relationship? Doesn't this require an additional API call? Is this efficient?</p>
  
  <p>The "included" section seems like it contains more detailed information about the relationships/associations?</p>
  
  <p>Are both "included" and "relationships" necessary? What's the intuition behind needing both of these sections?</p>