Load relationships without going through includes

https://twitter.com/mwpastore/status/969315305863417856

when I do foo.load(‘bar’), why does it hit /api/foo/1?include=bar instead of /api/foo/1/relationships/bar? The latter would allow me to e.g. filter foo’s bar collection. Maybe storefront needs an additional interface?

[ryanto]

I’ve had a few conversations with folks and I think I have some API changes that will solve a number of these cases.

Goal

To provide an API for explicitly loading relationship data. This allows for code that is easier to reason about. Calls to model.get('relationship') will return whatever data is in the store, while calls to model.load('relationship') will fetch data from the backend.

Current problem

load('relationship') uses a JSON:API include query to sideload a models relationship. While this works for most JSON:API backends, it does not work if the API layer wants the client to use relationship.links to load data.

Proposed solution

Add model.sideload('relationship'). This will work exactly how load works today, it will fetch the model and slideload it’s relationship. It will return a cached result if the relationship has already been loaded. Since it is using JSON:API’s include parameter to fetch data it has the added benefit of fetching multiple relationships in one go (example: post.sideload('comments.author,favorites')).

Change model.load('relationship') to use relationship.links. This will allow the client to fetch data from URLs provided by the backend without using the include pattern.

These new APIs will be backwards compatible, if you are using load() today it will continue to work.

Options

Each of these methods will take an options hash as its last parameter. This will allow for force reloading the relationships data.

model.sideload('relationship', { reload: true });
model.load('relationship', { reload: true });

It will also allow developers to implement their own query param logic by overloading the load method on a model-by-model basis. Since sending query param data while loading relationships is not supported by ember-data the user will have to write this logic themselves.

Other

Instead of naming the method sideload, we could call it include.

[ryanto]

Ok, this feature has been released in 0.14.0. 🎉

Two changes to load…

1. It now uses Ember Data to load the relationship, meaning it will respect your payloads relationship links.
2. It also returns a promise that resolves with the relationship.