We include parent (belongs_to) type relationships in serializations, but should not require n+1 to lookup all parents. This is especially powerful when coupled with the de-nesting strategy.
Addons include a plan. This is usually included in a summary that looks like:
{
...
"plan": {
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev"
},
...
}
Many use cases might want the full user info without looking everything up. By including a special header they could ask for this envelope to expand to include the entire parent serialization.
Accept-Expansion: plan
Content-Expansion: plan
{
...
{
"created_at": "2012-01-01T12:00:00Z",
"default": false,
"description": "Heroku Postgres Dev",
"human_name": "Dev",
"id": "01234567-89ab-cdef-0123-456789abcdef",
"name": "heroku-postgresql:dev",
"price": {
"cents": 0,
"unit": "month"
},
"state": "public",
"updated_at": "2012-01-01T12:00:00Z"
},
...
}
- Requests without
Accept-Expansion
behave as per normal. Accept-Expansion
can include more than one expansion, if so they should be comma-delimited.- If
Accept-Expansion
cannot be applied, server should return406 (Not Acceptable)
- Responses which include expansion should also have
Content-Expansion
header which includes the list of expanded values. - Endpoints which support expansion should return
Accept-Expansion
, which should contain a list of the allowed/implemented possible expansions. - NOTE: this is an easy way to inadvertently cause n+1 queries, so be careful that proper queries are setup to eager load associations.
- NOTE: we should pay careful attention to auth/access, you should not be able to expand things you wouldn't be able to lookup directly.
- Initially we will only support one level of depth in expansion (no expanding the envelope of on envelope), but in the future we may add this by virtue of colon delineation, ie
owner:default_organization
.