Support for more general json:api documents (links, data, meta)

[therealcljohn]

Hi,

I read the discussion about the roadmap in #19 so I'm going to create a new issue to have some space to discuss a topic that needs some more refactoring. I'm currently using this package in a small opensource client. The client makes use of HATEOAS and thus needs support for the top level link attribute in json:api.

Currently this package only handles the data attribute. But there is a RFC for ember-data that proposes how to implement support for more general json:api documents. If I got the idea of the RFC adapted to this package right, then you should be able to make a request to the API and get something like a DocumentModel (instead of a JsonApiModel) as response. The DocumentModel gives you access to all the top level attributes of a json:api document using the following getter methods:

• data(): JsonApiModel (existing JsonApiModel)
• links(): LinksModel (new model)
• meta(): MetaModel (new model)

A basic query then would look like this:

        this.datastoreService.query(User, {
            page: { size: 10, number: 1},
            include: 'roles'
        }).subscribe(
            (document: DocumentModel) => {
                // access to the JsonApiModel
                this.users = document.data();
                // access to the top level links attribute
                this.links = document.links();
                // access to the json:api document in general
                this.usersDocument = document
            }
        );

The response part is worth discussing. I think in the RFC they won't return a DocumentModel like I propose. Instead they return a JsonApiModel that has an getter method document() to access the top level attributes. Thus the programming API does not change. But this approach has a big disadvantage when adopting the RFC to this package. Because if you want to access the top level attributes of an empty collection this package will give you just an empty array as response. This is why I would propose to return a general DocumentModel instead of JsonApiModel or Array<JsonApiModel>.

All other parts of the package should not change. This means if you do peek() then you should get an JsonApiModel on which you can call document() to get the coresponding document including all the top level attributes like links() and meta().

For testing this approach I did a very basic implementation in my jsonapi-document branch and also adopted this changes into the client:

• jsonapi-document branch commit
• client commit

I'm going to further test this implementation next week but I just wanted to hook into the discussion about the roadmap with this proposal early so that you can consider this feature in further plans.

[HennerM]

I think it would be good to have a generic DocumentModel class with a type parameter used for the type of the data. So you can return both DocumentModel<JsonApiModel> or DocumentModel<JsonApiModel[]> and have better type checking.

[ghidoz]

Hi @floh1111, you are right: at the moment the library just handle the data attribute. As you suggest, we should also expose the links and meta objects.

Personally, I prefer to return directly the JsonApiModel rather than having to call the data() method on the DocumentModel, also because I suppose that the need of accessing links and meta is not so common.
On the other side, I can understand the disadvantage you are talking about.

I would like to hear from the other people who are using the library. What do you think?

[reva2]

Hi guys,

@ghidoz, I think that meta and links document objects widely used in many applications. The most common example is a pagination. So we definitely should give access to this data.

I like @floh1111 idea about returning DocumentModel that give user access to data, links, metadata and errors. But I agree with @HennerM. For better type checking and hinting it should be implemented using generics.

[ghidoz]

I absolutely agree on giving access to meta and ´links´. My only concern was about returning directly the data or the DocumentModel.

[reva2]

According to spec document should contain at least one of top-level members:

• data
• errors
• meta

I.e. it's absolutely legal to have document that contains only meta member. In this case if we will return empty data with additional property that will contain reference to document it can confuse users.

[HennerM]

I would like to leave this decision to the user of the library. There could be 2 different methods, one that just returns the models and one that returns the DocumentModel.
A proposal for these methods:

• findAll<T>(modelType: ModelType<T>, params?: any, headers?: Headers): Observable<T[]>
• query<T>(modelType: ModelType<T>, params?: any, headers?: Headers): Observable<DocumentModel<T[]>>

[rnikunen]

How soon can we see support for meta data? Right now I cannot do pagination cause I have no way of obtaining it :(

[HennerM]

Closing because this was part of 3.6 release.