improve consistency in v3 API

[bayareacoder]

Issue Description

To make it easier to integrate the API into frameworks that allow to build an Admin UI based on GraphQL introspection, it would help to have type, query and mutation names that are consistent:

1. Mutation operation names should include the name of the type, of the form <verb><type> where <verb> is as shown below

2. Queries should have the lowercase name of the type and exist in single form with id parameter, and in plural with optional filtering, Relay cursor inputs, and offset input params for easier pagination via page numbers, and then return a relay-compliant response (so both edges and nodes). See also issue#6252 that aims to address the lack of offset params on several queries and issues #6261 & #6263 that found plural queries missing edges in their responses.

3. Mutation operation names should be of the form: create<type>, update<type>, remove<type> (when it makes sense to remove; I noticed many entities do not have a remove probably to ensure database consistency)

To keep flexibility, you can have additional operations but at least the above should be supported for entities that would be considered 'resources' in an equivalent REST API, so likely everything that is a separate collection in the MongoDB.

Examples of inconsistencies:

• no shops query, only shop(id) - an issue when building multi-shop solution
• vice versa, emailTempates query does not have a singular version
• similar for discountCodes: no singular version
• emailTemplates works on the type Template, not EmailTemplate
• ...

To avoid breaking changes, the missing operation names and queries could just be added in addition to the current API.

Versions

reaction-api v3.8

[janus-reith]

Hi @bayareacoder, first of all, I agree on all three points you raised, especially regarding 3 I think some work could be done to generalize and simplify CRUD Operations.

To make it easier to integrate the API into frameworks that allow to build an Admin UI based on GraphQL introspection, it would help to have type, query and mutation names that are consistent

Could you elaborate further on the "Admin UI based on GraphQL introspection"? Do you just mean creating an Admin UI by looking at the GraphQL Schema availabe trough introspection, or actually technically making use of Introspection in the Admin?

[bayareacoder]

Hi Janus, I mean making use of graphql introspection in the admin. Actually we do that now in our admin UI for RC to create a ‘field list’ of the fields available so we can build the graphql query string from it without having to enumerate them in the source code.

[janus-reith]

@bayareacoder Awesome! I had a similar idea in mind for some time, but never actually implemented it. Would love to see what you came up with sometime if that is possible. Are you planning on open-source any part of it?

Regarding this ticket, I think it would be helpful to have a complete list if items that would need to be renamed/implemented to get a better picture of the amount of work this involves.

[bayareacoder]

We don't do open-source so can't share our code but we use similar to this, which is using the principle of using GraphQL introspection to build queries:https://github.com/marmelab/react-admin/tree/master/packages/ra-data-graphql As for a complete spec, besides the few examples I gave I don't have that as we are implementing with the current API, but in essence everything should be consistent in terms of parameters passed (eg shopId or pagination params), for every 'entity' there should be full CRUD support for both singular and plural queries & mutations, and entities/mutation/query names should all be consistent (eg no EmailTemplate while elsewhere it is called Template). But the bigger issue is that some functionality (accounts, jobs) is not available at all via the API at all as reaction-admin is using Meteor for that still.