Returning relationship entities in JSON.API response

I’m using the JSON-API to retrieve custom entities:

GET /api/courseofferings?filter[status]=A,C HTTP/1.1 Authorization:WSSE profile="UsernameToken" X-WSSE: UsernameToken Username="xxxxxx", PasswordDigest="xxxxxx", Nonce="xxxxxx", Created="xxxxxx" Content-Type:application/vnd.api+json

1 2 3 4

GET /api/courseofferings?filter[status]=A,C HTTP/1.1 Authorization:WSSE profile="UsernameToken" X-WSSE: UsernameToken Username="xxxxxx", PasswordDigest="xxxxxx", Nonce="xxxxxx", Created="xxxxxx" Content-Type:application/vnd.api+json

And I receive this response back from my application, as expected:

JavaScript

{ "data": [ { "type": "courseofferings", "id": "4", "attributes": { "status": "A", "createdAt": "2016-05-27T02:01:35Z", "updatedAt": "2016-07-02T17:25:11Z" }, "relationships": { "course": { "data": { "type": "courses", "id": "1" } }, "schedule": { "data": [ { "type": "courseofferingtimes", "id": "10" }, { "type": "courseofferingtimes", "id": "11" } ] } } } ] }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

{   "data": [     {       "type": "courseofferings",       "id": "4",       "attributes": {         "status": "A",         "createdAt": "2016-05-27T02:01:35Z",         "updatedAt": "2016-07-02T17:25:11Z"       },       "relationships": {         "course": {           "data": {             "type": "courses",             "id": "1"           }         },         "schedule": {           "data": [             {               "type": "courseofferingtimes",               "id": "10"             },             {               "type": "courseofferingtimes",               "id": "11"             }           ]         }       }     }   ] }

Is there a way I can ask the API to return the whole serialized related entity instead of just the relationship link (type+id)? There are certain circumstances where I’d like to batch together all the related data so I can get it in one request.

In the above example, for instance, I would presently need to do three API calls to render the schedule for this Course Offering (one to fetch the offering itself, two more to fetch each schedule entry of type “courseofferingtimes”)

(Technically I could do it in two calls by doing /api/courseofferingtimes?filter[id]=10,11 instead of separate calls to /api/courseofferingtimes/10 and /api/courseofferingtimes/11 — but that’s still two total calls where I’d like to do one)

Topic

[adamlundriganParticipant]

Not sure if it’s the best or most efficient way but it can be accomplished by enumerating the fields for each associated entity inline, like so:

(Note: these examples don’t use the same custom entity as I used in my original question)

YAML

oro_api: entities: Application\Bundle\RegistrationBundle\Entity\CourseRegistration: fields: courseOffering: fields: id: ~ status: ~ course: fields: id: ~ title: ~ titleSlug: ~ status: ~

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

oro_api:     entities:         Application\Bundle\RegistrationBundle\Entity\CourseRegistration:         fields:           courseOffering:             fields:              id: ~              status: ~              course:                fields:                  id: ~                  title: ~                  titleSlug: ~                  status: ~

The JSON.API response will now have an “included” key with serialized copies of each related entity. Example:

JavaScript

{ "data": { "type": "registrationcourseregistrations", "id": "21", "relationships": { "courseOffering": { "data": { "type": "courseofferings", "id": "2" } } }, "attributes": { "status": "P", "createdAt": "2016-07-05T15:47:26Z", "updatedAt": "2016-07-05T15:47:26Z" } }, "included": [ { "type": "courseofferings", "id": "2", "attributes": { "status": "A" }, "relationships": { "course": { "data": { "type": "courses", "id": "2" } }, "schedule": { "data": [] } } }, { "type": "courses", "id": "2", "attributes": { "title": "Another Test Course", "titleSlug": "another-test-course", "description": "Testing 12345", "status": "A", "createdAt": { "date": "2016-05-24 16:09:27.000000", "timezone_type": 3, "timezone": "UTC" }, "updatedAt": { "date": "2016-07-01 23:55:05.000000", "timezone_type": 3, "timezone": "UTC" } } } ] }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59

{   "data": {     "type": "registrationcourseregistrations",     "id": "21",     "relationships": {       "courseOffering": {         "data": {           "type": "courseofferings",           "id": "2"         }       }     },     "attributes": {       "status": "P",       "createdAt": "2016-07-05T15:47:26Z",       "updatedAt": "2016-07-05T15:47:26Z"     }   },   "included": [     {       "type": "courseofferings",       "id": "2",       "attributes": {         "status": "A"       },       "relationships": {         "course": {           "data": {             "type": "courses",             "id": "2"           }         },         "schedule": {           "data": []         }       }     },     {       "type": "courses",       "id": "2",       "attributes": {         "title": "Another Test Course",         "titleSlug": "another-test-course",         "description": "Testing 12345",         "status": "A",         "createdAt": {           "date": "2016-05-24 16:09:27.000000",           "timezone_type": 3,           "timezone": "UTC"         },         "updatedAt": {           "date": "2016-07-01 23:55:05.000000",           "timezone_type": 3,           "timezone": "UTC"         }       }     }   ] }

[adamlundriganParticipant]

Thanks to @vsoroka on GitHub for pointing out a better way to do this (link). I didn’t think to look at the JSON.API docs, which in hindsight seems a pretty obvious course of action :/

JSON.API has an “include” query string parameter which specifies the related entities that should be included in the response.

[Author]

Replies