Working with data on relationships

19

@Sazzer - We have a very similar challenge. Our pragmatic solution has been to use the meta property for the relationship if the additional data to be carried with it is simple (e.g. a single numerical value). We’ve even stretched this a bit further to the point of having a handful of values in meta. I think that goes against the intent of the JSON API spec but is a pragmatic solution. However, when relationships get very complex, we break them out so they exist as their own independent endpoints that have relationships to the other entities as well as their own attributes.

Simplifying the example, here’s the gist of what it would look like as a simple property stored in the meta object:

{
  "data": {
    "type": "characters",
    "id": "1234",
    "attributes": {}
    "relationships": {
      "skills": {
        "data": [
          {
            "type": "skills",
            "id": "swords",
            "meta": {
              "level": 15
            }
          },
          {
            "type": "skills",
            "id": "bows",
            "meta": {
              "level": 20
            }
          }
        ]
      }
    }
  }
}

When things get complex, we make the relationship it’s own entity. E.g. assume the skill had not-only a level but an acheivement date, some details around the mission where they earned the skill, etc. Then we’d model it more like this:

{
  "data": {
    "type": "characters",
    "id": "1234",
    "attributes": {}
    "relationships": {
      "character-skills": {
        "data": [
          {
            "type": "character-skills",
            "id": "a6002dd1-d71f-481c-9291-9df338f77f72"
          },
          {
            "type": "character-skills",
            "id": "63c905c2-7288-4f0e-be1d-520b8727c8c7"
          }
        ]
      }
    }
  }
  "included": [
    {
      "type": "character-skills",
      "id": "a6002dd1-d71f-481c-9291-9df338f77f72",
      "attributes": {
        "level": 15,
        "achieved": "2017-12-14",
        "mission": {
          "title": "Save the Princess",
          "duration": 15376,
          "battles": 12
        }
      },
      "relationships": {
        "skill": {
          "data": {
            "type": "skills",
            "id": "swords"
          }
        },
        "owner": {
          "data": {
            "type": "characters",
            "id": "1234"
          }
        }
      }
    },
    ... etc.
  ]
}

You are right that you can’t create a character and their skills this way in one fell swoop. That’s why we bend the rules for simple stuff and use meta. For complex relationships, we find the better representation outweighs the hassle of multiple calls.

I hope this helps.