Relationships level or basic rules joining related resourses



I have tried to google and search in this disccuss board but with no luck. It’s possible that following question is too abstract and arose because i missed something in specification or here in search results.

The question is about how to handle resourses which are related to each other and also how i should ( by convention ) access these resourses and when i should use relationship between them and when i should access them as seperate resourses.

There’s concrete example. Let’s assume that we have resourses that are related to each other: Countries, States and Cities. So, countries has many states, states has many cities and i’m going implement something like this:

The first idea is to have three seperate endpoints:

  • /v1/module/countries
  • /v1/module/states
  • /v1/module/cities

There’s a workflow:

Retrieved all countries from countries endpoint and have chosen “Vietnam”.
Now i need to retrieve all Vietnam states.
When i got all states in some way i have chosen An Giang state and now i need to get all cities for this state.

Should i use here relationship or not and in case i should how it should look like?

There’s some mine thoughts:

  • /v1/counties/country:id/relationship/states -
  • /v1/states/states:id/relationship/cities

Or should i use just links to original resourses:

  • /v1/states?filter[country:id]=country:id
  • /v1/cities?filter[state:id]=state:id

If i do understand correctly all these relationships are just links to original resourse just represended in relationship manner. /v1/counties/country:id/relationship/states actualy is link to /v1/states?filter[country:id]=country:id ?

Also i would appreaciate any guidliness related API development.


I have done some research:

From here: Usage of `related` field in Relationships link

So, in real word example ( from my previous post ) i believe it should like something like this:

GET /v1/module/countries

  "links": {
    "self": ""
  "data": {
    "id": "county_id",
    "type": "countries",
    "relationships": {
      "state": {
        "links": {
          "related": "" // states is plural, it's ok?
        "data": {"id": "state_id", "type": "state"}

  "included": [{
    "id": "state_id",
"type": "state",
"attributes": {

"relationships": {
  "cities": {
    "links": {
      "related": ""  // cities is plural, it's ok?
    "data": {
      "id": "cities", // what about cities id
      "type": "accountProfile"

According this resource: Is it ok to add multiple levels of nested relationships in the relationships field

But still i feel like missing something and confused about all these relationships and i don’t see any logical reasoning and connections between this complexity.