Sparse relationships

[cmars]

Similar to sparse fieldsets & #159, what if we want to express sparse relationships in JSON API?

A resource might relate to many other resources. However, in fulfilling a request, it might be expensive to provide all of them. Consider that each relationship might require a table join in order to determine existence and resolve the public identifier. Or worse yet, an internal service-to-service API request.

We can express sparse relationships using a relationships parameter, with a notation similar to sparse fieldsets.

• If relationships is not defined as a parameter, resource does not support sparse relationships and returns all of them if it has them.
• If relationships is defined as a parameter:
  • It must be style: form, explode: false. This defines a comma-separated []string like ?relationships=a,b,c.
  • No relationship parameter present in the request means I'm not filtering relationships, so "give me everything"
  • ?relationships= means "I don't want any relations at all" (empty or omitted relationships)

Given a resource like:

data: {
  id: some-id,
  type: some-resource,
  relationships: {
    org: {id: some-org, type: org, links: {related: /orgs/some-org}},
    group: {id: some-group, type: group, links: {related: /groups/some-group}},
    target: {id: some-target, type: target, links: {related: /targets/some-target}},
    snapshot: {id: some-snapshot, type: snapshot, links: {related: /snapshots/some-snapshot}},
    monitor: {id: some-snapshot, type: snapshot, links: {related: /snapshots/some-snapshot}},
  },
}

We might request a subset of these with GET /some-resource/some-id?relationships=org,group:

data: {
  id: some-id,
  type: some-resource,
  relationships: {
    org: {id: some-org, type: org, links: {related: /orgs/some-org}},
    group: {id: some-group, type: group, links: {related: /groups/some-group}},
  },
}

or none at all with GET /some-resource/some-id?relationships=:

data: {
  id: some-id,
  type: some-resource,
}