Refactor the Serializer API

[wecc]

This PR refactors the way serializers normalizes adapter responses. serializer.extract() is now deprecated for the new serializer.normalizeResponse().

normalizeResponse() is expected to return a JSON-API Document with primary and, if any, secondary/sideloaded/included as { data, included }.

normalize() is also expected to return a JSON-API Document having the primary data be the normalized record in { data } and, if any, secondary data (e.g. embedded) in { included }.

This change should be fully backwards compatible. For users to opt-in to the new Serializer API they should convert their existing extract() hooks to normalizeResponse() hooks and make it return JSON-API. Then add isNewSerializerAPI: true in their serializer(s).

Todos

• Rename REST2Serializer, EmbeddedRecords2Mixin and ActiveModel2Serializer to something that makes sense
• Figure out what and how to deprecate the old API
• Feature flag / set isNewSerializerAPI for non-extended serializers
• Create hooks to make it easier to customize normalizeResponse()
• Break up normalizeResponse() to reflect the old extractArray/extractSingle methods
• Add deprecation notices

[igorT]

@wecc you forgot to mention JSON2Serializer

[sly7-7]

I'm probably missing something, but why not naming those classes as JSONAPIXxx ?

[bmac]

I think the fear is that JSONAPI in the name will be confusing because the new "2" serializers are not intended to be used with a JSONAPI backend. They simply transform a non JSONAPI data into JSON API format, with the eventual goal of Ember Data using json api natively, allowing 3rd party serializer authors to target JSON API instead of the unspecified "normalized" format that Ember Data uses today.

[sly7-7]

@bmac Thanks, that makes sense

[bmac]

Looks like this method is repeated in the rest2-serializer rest-serializer and store module. Lets move it into its own file and import it in all 3 places.

[wecc]

Done!

[wecc]

default to return this._normalizeResponse(...arguments)

[fivetanley]

could also dry this up to this['normalize' + capitalize(requestType)] || this._normalizeResponse)

[wecc]

I have this vague memory that we wanted to change this to switch to make it easier for people to see what actual requestTypes are getting passed. We just never got around to change it here. The discussion was originally around https://github.com/emberjs/data/blob/master/packages/ember-data/lib/adapters/build-url-mixin.js#L52-L75

[igorT]

👍 on structuring the commits

[tomdale]

s/an/a/

[igorT]

Don't need this todo anymore

[igorT]

👍