Create and include related objects (updated example)

You can include related object(s) details in responses with the query string parameter named “include”. You can use the “include” parameter on any kind of route (classical CRUD route or relationships route) and any kind of HTTP methods as long as the method returns data.

This feature will add an additional key in the result named “included”

Example

Create user

Request:

POST /users HTTP/1.1
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "user",
    "attributes": {
      "first_name": "Bob",
      "last_name": "Green",
      "age": 37,
      "status": "active",
      "email": "bob@example.com"
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "data": {
    "attributes": {
      "age": 37,
      "email": "bob@example.com",
      "first_name": "Bob",
      "last_name": "Green",
      "status": "active"
    },
    "id": "3",
    "type": "user"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "meta": null
}

Create computer for user and fetch related user

Request:

POST /computers?include=user HTTP/1.1
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "computer",
    "attributes": {
      "name": "Amstrad"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "3",
          "type": "user"
        }
      }
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "data": {
    "attributes": {
      "name": "Amstrad"
    },
    "id": "2",
    "relationships": {
      "user": {
        "data": {
          "id": "3",
          "type": "user"
        }
      }
    },
    "type": "computer"
  },
  "included": [
    {
      "attributes": {
        "age": 37,
        "email": "bob@example.com",
        "first_name": "Bob",
        "last_name": "Green",
        "status": "active"
      },
      "id": "3",
      "type": "user"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": null
}

Get user

Request:

GET /users/3 HTTP/1.1
Content-Type: application/vnd.api+json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "attributes": {
      "age": 37,
      "email": "bob@example.com",
      "first_name": "Bob",
      "last_name": "Green",
      "status": "active"
    },
    "id": "3",
    "type": "user"
  },
  "jsonapi": {
    "version": "1.0"
  },
  "meta": null
}

Get user with related computers

Request:

GET /users/3?include=computers HTTP/1.1
Content-Type: application/vnd.api+json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "attributes": {
      "age": 37,
      "email": "bob@example.com",
      "first_name": "Bob",
      "last_name": "Green",
      "status": "active"
    },
    "id": "3",
    "relationships": {
      "computers": {
        "data": [
          {
            "id": "2",
            "type": "computer"
          }
        ]
      }
    },
    "type": "user"
  },
  "included": [
    {
      "attributes": {
        "name": "Amstrad"
      },
      "id": "2",
      "type": "computer"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": null
}

Get users

Request:

GET /users HTTP/1.1
Content-Type: application/vnd.api+json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "attributes": {
        "age": 21,
        "email": "john@example.com",
        "first_name": "John",
        "last_name": "Smith",
        "status": "active"
      },
      "id": "1",
      "type": "user"
    },
    {
      "attributes": {
        "age": 42,
        "email": "sam@example.com",
        "first_name": "Sam",
        "last_name": "White",
        "status": "active"
      },
      "id": "2",
      "type": "user"
    },
    {
      "attributes": {
        "age": 37,
        "email": "bob@example.com",
        "first_name": "Bob",
        "last_name": "Green",
        "status": "active"
      },
      "id": "3",
      "type": "user"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "count": 3,
    "totalPages": 1
  }
}

Get users with related computers

Request:

GET /users?include=computers HTTP/1.1
Content-Type: application/vnd.api+json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "attributes": {
        "age": 21,
        "email": "john@example.com",
        "first_name": "John",
        "last_name": "Smith",
        "status": "active"
      },
      "id": "1",
      "relationships": {
        "computers": {
          "data": []
        }
      },
      "type": "user"
    },
    {
      "attributes": {
        "age": 42,
        "email": "sam@example.com",
        "first_name": "Sam",
        "last_name": "White",
        "status": "active"
      },
      "id": "2",
      "relationships": {
        "computers": {
          "data": [
            {
              "id": "1",
              "type": "computer"
            }
          ]
        }
      },
      "type": "user"
    },
    {
      "attributes": {
        "age": 37,
        "email": "bob@example.com",
        "first_name": "Bob",
        "last_name": "Green",
        "status": "active"
      },
      "id": "3",
      "relationships": {
        "computers": {
          "data": [
            {
              "id": "2",
              "type": "computer"
            }
          ]
        }
      },
      "type": "user"
    }
  ],
  "included": [
    {
      "attributes": {
        "name": "ZX Spectrum"
      },
      "id": "1",
      "type": "computer"
    },
    {
      "attributes": {
        "name": "Amstrad"
      },
      "id": "2",
      "type": "computer"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "count": 3,
    "totalPages": 1
  }
}