Hello, everybody!
We are building APIs for our university. While building the JSON docs following JSON:API spec, we realized that we have a considerable amount of “catalogs” of the form {“key”: “abc”, “description”: “XYZ” }. When trying to represent a resource that has many of these key-description fields as attributes, we first tried to represent the catalogs as resources and used the relationships and included objects, but then noted that the resulting JSON document grows considerably, as below:
{
"data": {
"type": "student",
"id": "studentID",
"attributes": {
"firstName": "First Name",
"lastName": "Last Name",
},
"relationships": {
"has-gender": { "data": { "type": "genders", "id": "M" } },
"has-nationality": { "data": [ { "type": "nationalities", "id": "01" },
{ "type": "nationalities", "id": "02" } ],
"has-status": { "data": { "type": "student-status", "id": "R" } }
},
"included": [
{
"type": "genders",
"id": "M",
"attributes": {
"description": "Male"
}
},
{
"type": "nationalities",
"id": "01",
"attributes": {
"description": "Mexican"
}
},
{
"type": "nationalities",
"id": "02",
"attributes": {
"description": "US American"
}
},
{
"type": "student-status",
"id": "R",
"attributes": {
"description": "Regular"
}
}
]
}
}
This is for a single student representation. We then thought about including the foreign keys as attributes of the student, together with their corresponding descriptions in an object, as follows:
{
"data": {
"type": "student",
"id": "studentID",
"attributes": {
"firstName": "First Name",
"lastName": "Last Name",
"gender": { "genderKey": "M", "genderDescription": "Male" },
"nationalities": [ { "nationalityKey": "01", "nationalityDescription": "Mexican" },
{ "nationalityKey": "02", "nationalityDescription": "US American" } ],
"student-status": { "statusKey": "R", "statusDescription": "Regular" }
}
}
}
This is just an example, but we have resources that contain more than 10 attributes of this type and become very verbose when using relationships.
Is the last approach “correct”? I read in the spec that foreign keys SHOULD NOT be part of the attributes of a resource, but precisely because it says “SHOULD NOT”, and not “MUST NOT”, is that we are considering this approach.
We could define to set as attributes only the descriptions, but in some cases the consumer could need the keys to perfom some other operations.
Any comments are welcome. Thank you!