Record Data Errors RFC.md

Errors RFC

• Start Date: (fill me in with today's date, YYYY-MM-DD)
  • Relevant Team(s): (fill this in with the team(s) to which this RFC applies)
  • RFC PR: (after opening the RFC PR, update this with a link to it and update the file name)
  • Tracking: (leave this empty)

Summary

This RFC is a follow-up RFC for #293 RecordData.

Exposes the content of Invalid Errors returned by the adapter on Record Data.

Motivation

Currently Record Data manages and exposes all of the attributes and relationships for a record. However, the initial version of Record Data made the choice to not expose error information in order to limit the scope of the RFC and to give us time to come up with a design. This RFC, together with the Request State RFC, addresses this capability gap.

When a user sends a record save request, it can fail in two different ways:

• It can fail as a generic Adapter Error, and put the record in an isError state. This corresponds to any failure, including those such as the network being down, server returning 500s or the auth layer returning a 401. Because these errors are not tied to the Record or it's data, they do not belong in the Record Data layer and will be exposed separately as part of the Request State RFC
• However, the request can also fail with a more specific InvalidError This currently puts the record in the invalid state. InvalidError corresponds to a specific validation failure of the request being made. Currently, the default adapter implementation creates an InvalidError if the server returns a 422 . InvalidError payload follows the JSON API error object spec, and if the error payload contains pointers those get mapped to attributes on a record. Because an Invalid Error maps to the data on a record, it should be managed by Record Data together with the attributes and relationships.

Detailed design

Currently on a failed save, Record Data receives a call to

commitWasRejected(recordIdentity: RecordIdentity): void;

This RFC proposes passing an optional errors object that would follow the JSON api errors spec, only in case an invalid error has been returned:

interface JsonApiValidationError {
  title: string;
  detail: string;
  source: {
    pointer: string;
    parameter?: string
  }
}

commitWasRejected(recordIdentity: RecordIdentity, errors?: JsonApiValidationError[]): void;

We would also expose a getter for errors,:

getErrors(recordIdentity: RecordIdentity): JsonApiValidationError[]

There would be no client side write api. Currently DS.Model handles a lot and that would be isolated to the Model layer.

Unresolved questions

Currently Record Data notifies whenever there are changes to the attributes or relationships. Do we need a notification api? If so what would be the notification api?