[FR] JSON:API compliance - links

[MaSpeng]

Is your feature request related to a problem? ^*

From my current point of view, this library does not allow to add other links, besides pagination, then self or related to the document or resource. The JSON:API specification does not describe a restriction to this.

As an example, it is not possible to describe an API entry point that only contains links and might also contain document metadata.

Describe the solution you'd like^*

I could imagine, that the properties document and resource in the linkers option will allow a map containing the link names, self as an example, as the key, and the Linker as the value.

Example:

return new Serializer('', {
  version: null,
  linkers: {
    document: {
      self: new Linker(() => 'https://example.com/api'),
      resource: new Linker() => 'https://example.com/api/resources').
    },
  },
  metaizers: {
    document: new Metaizer(() => ({
      foo: 'bar',
    })),
  },
}).serialize(undefined);

Another solution might be that the Linker could return a map of links:

Example:

return new Serializer('', {
  version: null,
  linkers: {
    document: new Linker(() => ({
      self: 'https://example.com/api',
      resource: 'https://example.com/api/resources'
    })),
  },
  metaizers: {
    document: new Metaizer(() => ({
      foo: 'bar',
    })),
  },
}).serialize(undefined);

Describe alternatives you've considered^*

Serializing resources with other links by hand or amending the serialization result.

[jrandolf]

Thanks for the issue.

We thought about this during development, and the solution we came up with was to just use metaizers. The JSON:API spec, indeed, does not restrict what you desire, however if you look closely...the standard rarely restricts anything. In fact, all standards I've seen leave it up to the company when it comes to really "extra" stuff.

My advice is to use metaizers, and if that is not possible, fork this repo! Try to keep an API similar to this repo so upstream changes don't upset yours.

[MaSpeng]

Thanks for your fast response, sure metaizers would allow me to provide extra information at my own will. From my point, this should not be the place to provide links especially if they point to the API itself.

Sure this is my opinion and not described in the specification itself, it just feels like common sense to me to put links to links 😏.

Would you like to close this issue or keep it for the backlog for further improvements?

[jrandolf]

I'll back log this. The linker change sounds like an API feature I would be interested in implementing for V2. Your argument is sensible, but first and foremost, the change would look natural and would alleviate the constant Linker declarations.