ember-learn / ember-learn/guides-source

Quest - Improvements to teaching Ember Data

Open
#20 13 comments 6 reactions 0 assignees View on GitHub
help wanted
Dominant language
HTML
Stars
161
Forks
512
Avg merge
4d 9h
Merged PRs (30d)
4

Description

Let's teach Ember Data better! Developers face three main hurdles when learning Ember Data, and by completing the issues linked below, we can improve the learning story. The challenges at a high level are:

1. Not knowing where the line is between Ember and Ember Data
2. Hard to know which API methods to use when
3. Fundamental misunderstanding of the point of serializers, as a way to turn any response into JSON:API

Here's how we'll overcome these. PRs should branch from `master` and target `master` for a merge.

- [ ] Find the places in the Guides where Ember Data functions are referenced, outside of the "Ember Data" section of the guides. Add an explicit note that the example uses Ember Data, and maybe a link to that part of the Guides or API docs.
- [ ] Show sample req and res objects/spec for different adapters/serializers
- [ ] Replace "customizing" language for serializers. I think we could simplify the mental model for everyone by teaching more about what a serializer is and how to write one instead of focusing on “customizing”
- [ ] Focus serializer explanations around most useful API methods. There are only 3 necessary methods, only 2 of which are “happy path”. Those methods are `normalizeResponse` `serialize` and `pushPayload`, and each can be described in an ideal world as “a pure function that converts from non-json-api to json-api or vice-versa”. The 2 happy path methods are `normalizeResponse` and `serialize`
- [ ] make sure distinction between `model` and `record` is clear. `record` for instances and `ModelClass` for the class
- [ ] better intro explaining what adapters are
- [ ] overall, gradually align on json-api terminology within ember-data, e.g. instead of saying `record` say `resource` and `resource-identifier`
- [x] provide a proper intro to Ember Data in the Guides
- [ ] Split out Ember Data into its own Guide (way down the road, after we do the same for Tutorials)

Helpful terminology definitions:
- `store`: a cache for `records`
- `Model`: a schema class used when instantiating a `record`
- `Adapter`: a request-manager: it takes instructions on what to find and manages the process of making an API request and returning the response. Essentially an abstraction over fetch.
- `Serializer`: a formatter used to convert your API responses into json-api format if they are not already (caveat, needs to be a subset of json-api (camelCase member names and dasherized, singularized types)
- `finders`: a utility method for chaining together `request => format data => update cache`
- `records` (e.g. instances of Models) - think of them as “remote state”. A `record` is some data that lives outside of the lifecycle of the application, e.g. on your server

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.