API Relation Expansion

relation_expansion.md

Given an object has an owner association (relation), when expanded by default it will be exposed as:

{
  "name": "service-production",
  "owner": {
    "id": "5d8201b0...",
    "name": "Alice",
    "email": "alice@heroku.com"
  },
  ...
}

If, for performance reason, an association (relation) is not included but made available via expansion or a subsequent HTTP request, it will be referenced as:

{
  "name": "service-production",
  "owner_id": "5d8201b0...",
  "links": [
    { "name": "Owner", "rel": "https://api.example.com/rels/owner", "href": "https://api.example.com/users/01234567-89ab-cdef-0123-456789abcdef" }
  ]
  ...
}

If the owner key is not present, then we know a subsequent request is needed.

If owner is always present, then the client would need to inspect the owner object to see if it has the name and email.

What is the reason for separating the link from the owner?

How about:

{
    "name": "service-production",
    "owner_ref": {
        "id": "5d8201b0...",
        "link": { "name": "Owner", "rel": "https://api.example.com/rels/owner", "href": "https://api.example.com/users/01234567-89ab-cdef-0123-456789abcdef" }
    }
}

This would have 3 advantages:

1. shows the relationship between the link and the non-expanded relation more clearly (for humans)
2. works well when you have more than one non-expanded relation
3. easier for the client to find the link (although admittedly it is not too difficult to start with):