Is my usage of nested resources and relations approach are right?

1

Hello,

I’m implementing jsonapi spec in our API and i want make sure that i understand everything correctly.
Here’s full nested resource url: /v1/countries/1/states/42

I will give response output by going through all resources. Maybe something should or can be improved here?

Endpoint: /v1/countries

{
  "data": [
    {
          "type": "country",
          "id": "4",
          "attributes": {
            "country": "American Samoa",
            "calling_code": {
              "0": 1684
            }
          }
        }
      ]
    }

Endpoint: /v1/countries/4

{
  "data": {
    "type": "country",
    "id": "4",
    "attributes": {
      "country": "American Samoa",
      "calling_code": {
        "0": 1684
      }
    },
    "relationships": {
      "states": {
        "data": [
          {
            "type": "state",
            "id": "164"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "state",
      "id": "164",
      "attributes": {
        "state": "Eastern"
      }
    }
  ]
}

Endpoint: /v1/countries/4/states

{
  "data": [
    {
      "type": "state",
      "id": "164",
      "attributes": {
        "state": "Eastern"
      }
    },
    {
      "type": "state",
      "id": "165",
      "attributes": {
        "state": "Manu'a"
      }
    }
  ]
}

Endpoint: /v1/countries/4/states/164

{
  "data": {
    "type": "state",
    "id": "164",
    "attributes": {
      "state": "Eastern"
    },
    "relationships": {
      "cities": {
        "data": [
          {
            "type": "city",
            "id": "6414"
          },
          {
            "type": "city",
            "id": "6415"
          }
        ]
      }
    },
    "included": [
      {
        "type": "city",
        "id": "6414",
        "attributes": {
          "city": "Afono"
        }
      },
      {
        "type": "city",
        "id": "6415",
        "attributes": {
          "city": "Alao"
        }
      }
    ]
  }
}

Thanks!

2

It looks valid to me.

Will you be including any links? They are optional but for me those hypermedia references is the power of using JSON Api.

3

Thanks for taking a look!

Yes, i’m going to consider add these ( links ), thanks for your note.
In this example they are missing because i wanted to make sure that everything else is good.

4

Why would the returned data in the array not include the relationship objects? Why would you need to fetch them individually at /v1/countries/4?