Request/Response Examples

Fetch a User’s Citizenship Relationships

Request: /users/1/relationships/citizenships

Response:

{
  "data": [
    {
      "id": "NO",
      "type": "countries"
    },
    {
      "id": "FI",
      "type": "countries"
    }
  ],
  "links": {
    "self": "/users/1/relationships/citizenships",
    "first": "/users/1/relationships/citizenships",
    "next": "/users/1/relationships/citizenships?page%5Bcursor%5D=DoJu",
    "related:countries": {
        "href": "/countries?filter[id]=FI,NO",
        "meta": {
          "ids": ["FI", "NO"]
        }
    }
  },
  "meta": {
    "pagination.nextCursor": "DoJu"
  }
}

It’s worth noting that each relationship has its own pagination. The link to the next page can be found in the response under links -> next.

For example, to fetch the second page of a user’s citizenships relationship, try: /citizenships?page[cursor]=DoJu](http://localhost:8080/jsonapi/users/1/relationships/citizenships?page%5Bcursor%5D=DoJu)

Fetch a User’s Citizenship Relationships Along with Corresponding Country Resources

Request: /users/1/relationships/citizenships?include=citizenships

Response:

{
  "data": [
    {
      "id": "NO",
      "type": "countries"
    },
    {
      "id": "FI",
      "type": "countries"
    }
  ],
  "links": {
    "self": "/users/1/relationships/citizenships?include=citizenships",
    "first": "/users/1/relationships/citizenships?include=citizenships",
    "next": "/users/1/relationships/citizenships?include=citizenships&page%5Bcursor%5D=DoJu",
    "related:countries": {
        "href": "/countries?filter[id]=FI,NO",
        "meta": {
          "ids": ["FI", "NO"]
        }
    }
  },
  "meta": {
    "pagination.nextCursor": "DoJu"
  },
  "included": [
    {
      "attributes": {
        "name": "Norway",
        "region": "Europe"
      },
      "links": {
        "self": "/countries/NO"
      },
      "id": "NO",
      "type": "countries"
    },
    {
      "attributes": {
        "name": "Finland",
        "region": "Europe"
      },
      "links": {
        "self": "/countries/FI"
      },
      "id": "FI",
      "type": "countries"
    }
  ]
}

Fetch Multiple Countries by IDs

Request: /countries?filter[id]=US,NO

Response:

{
"data": [
    {
      "attributes": {
        "name": "Norway",
        "region": "Europe"
      },
      "links": {
        "self": "/countries/NO"
      },
      "id": "NO",
      "type": "countries"
    },
    {
      "attributes": {
        "name": "United States",
        "region": "Americas"
      },
      "links": {
        "self": "/countries/US"
      },
      "id": "US",
      "type": "countries"
    }
  ],
  "links": {
    "self": "/countries?filter%5Bid%5D=US%2CNO"
  }
}

Fetch a Specific Page of Users with Citizenship Linkage Objects and Resolved Country Resources

Request: /users?page[cursor]=DoJu&include=citizenships

Response:

{
  "data": [
    {
      "attributes": {
        "fullName": "Jack Doe",
        "email": "jack@doe.com"
      },
      "relationships": {
        "citizenships": {
          "data": [
            {
              "id": "US",
              "type": "countries"
            },
            {
              "id": "FI",
              "type": "countries"
            }
          ],
          "links": {
            "self": "/users/3/relationships/citizenships",
            "related:countries": {
                "href": "/countries?filter[id]=FI,US",
                "meta": {
                  "ids": ["FI", "US"]
                }
            }
          }
        }
      },
      "links": {
        "self": "/users/3"
      },
      "id": "3",
      "type": "users"
    },
    {
      "attributes": {
        "fullName": "Jessy Doe",
        "email": "jessy@doe.com"
      },
      "relationships": {
        "citizenships": {
          "data": [
            {
              "id": "NO",
              "type": "countries"
            },
            {
              "id": "US",
              "type": "countries"
            }
          ],
          "links": {
            "self": "/users/4/relationships/citizenships",
            "related:countries": {
                "href": "/countries?filter[id]=NO,US",
                "meta": {
                  "ids": ["NO", "US"]
                }
            }
          }
        }
      },
      "links": {
        "self": "/users/4"
      },
      "id": "4",
      "type": "users"
    }
  ],
  "links": {
    "self": "/users?include=citizenships&page%5Bcursor%5D=DoJu",
    "first": "/users?include=citizenships",
    "next": "/users?include=citizenships&page%5Bcursor%5D=DoJw"
  },
  "meta": {
    "pagination.nextCursor": "DoJw"
  },
  "included": [
    {
      "attributes": {
        "name": "Norway",
        "region": "Europe"
      },
      "links": {
        "self": "/countries/NO"
      },
      "id": "NO",
      "type": "countries"
    },
    {
      "attributes": {
        "name": "Finland",
        "region": "Europe"
      },
      "links": {
        "self": "/countries/FI"
      },
      "id": "FI",
      "type": "countries"
    },
    {
      "attributes": {
        "name": "United States",
        "region": "Americas"
      },
      "links": {
        "self": "/countries/US"
      },
      "id": "US",
      "type": "countries"
    }
  ]
}