Skip to content

Instantly share code, notes, and snippets.

@geemus
Last active August 29, 2015 14:18
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save geemus/6b0d59b5813d765c5267 to your computer and use it in GitHub Desktop.
Save geemus/6b0d59b5813d765c5267 to your computer and use it in GitHub Desktop.
Rough spec for API expansions

Expansion

Motivations

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.

Example

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"
  },
  ...
}

Implementation

  • 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 return 406 (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.

Possible extensions

  • 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment