Describe specification for the cache updates in the offix

[wtrocki]

Feature Request

There are numerous issues happening with offix that are related to the unwritten format of the mutations that users need to conform to.
This brings a lots of challenges to developers and they cannot evaluate how offix can be used and how to design their mutations for offix.

If they cannot design their mutations or they get some issues it is usually hard for us to react to the problem as we really missing the context of someone else cache or structure of their data.

Proposed solutions

Specify what format of queries offix supports

There is an easy way to address this problem without rewriting offix or changing premises. We need to call out the format of the data that offix expects to work with and provide support for that types of the data. Leaving developers to handle different cases separately. We can effectively use https://graphqlcrud.org specification as format for the queries that offix supports officially and provide the best case handling for the other frameworks.

Provide out of the box helpers and integrations with proposed format

It should be possible to swap to use offix when generating code facades using graphql code generator. We should have first class integration with graphql code generation - offix can use annotations or directives to mark offline enabled updates - this way we will also reduce amount of maintenance for the failed ideas like offix-hooks (developers will use codegen wrappers with the hook functionality insteead)

Give the ability to interact with the cache directly for flexibility of data deduplication and deletion

In situations when cache is not easy to be updated we should be able to provide direct access to the data (assuming some certain ID format).
Developers can now hack this on top of the apollo by building some graphql queries, but that is still challenging (mainly because of the way that apollo client works and lack of responses on PRs that they have created.
We should be able to duplicate data automatically for pagination and subscriptions

Depends on

#466

Affected issues

#334
#451
#447
#63
#71
#70
#70
#75
https://github.com/aerogear/offix/issues/463
#456

[kingsleyzissou]

@wtrocki I think this is sort of there now, but I think it needs to be documented better.

We definitely need to make it clear that the datastore now expects the structure of the data to conform to the GraphQL crud specification. Do you think we should add a complete section on this in the docs? Or should we just link to the grapqhcl crud page?

[wtrocki]

This is offix 1.0. Closing