Added ability to override schema options, added tests, updated docs

[alechirsch]

This allows the user to override a schema on a particular serialize call.

The use case I had for this was that on every request, each user might have their own permissions on what columns they are allowed to retrieve. This provides the ability to configure white list and black lists for attributes per call.

[coveralls]

Coverage remained the same at 100.0% when pulling 47ff72a on alechirsch:override-schema-options into 04f9a8a on danivek:master.

[danivek]

Interesting addition.

I never had this use case with json-api-serializer. Generally, I filter the data in the business logic layer before serialization because we can have many interfaces to expose the data (not only a REST endpoint with JSON:API).

If you want to do it with json-api-serializer, I think the best approach, is to create a new instance of a serializer on each request. It allows you to register a per request schema and serialize it.

Exemple:

const commonPersonSchema = {
  relationships: {
    address: {
      type: 'address'
    }
  }
};

// Per request Serialization
function(req, res) {
  const serializer = new JSONAPISerializer();
  const overridePersonSchema = {
    convertCase: 'camelCase',
    blacklist: ['social-security-number']
  };

  serializer.register('person', { ...commonPersonSchema, ...overridePersonSchema });
  const serializedData = serializer.serialize('person', data);
  // ...
};

What do you think about it ?

[alechirsch]

The issue that we are facing is that if we want to serialize a deeply nested relationship, recreating the serializer would be a hassle and waste of cycles.

On server start up we create the serializer for the entire API, with over 100+ models and tons of relationships between all of them. So for example as a simplified case if a request is made to model a, and the user wants to include b.c.d.e.f.g.h.i.j.k and they are not allowed to see a certain column on i, then rebuilding the serializer for that per request would be a lot.

I think having the ability to take an existing serializer, giving it some additional options to change its behavior on a single call can be very useful. With this change, to support the above example we would pass in an override for the type of i, and the existing serializer would stay intact.