GraphQL support

[jonasraoni]

We've considered adding support for GraphQL, so here's a list with pros/cons to help us reason if it's worth, when to introduce it, etc.

Pros

• Self-documented: The documentation is part of its specification, so we have a kind of swagger for free that can be consumed by 3rd-party clients. It's also possible to add descriptions to the fields and/or mark them as deprecated.
• It's relatively simple to extend a query/response with extra fields dynamically (our basic case of having a base definition in pkp-lib, which is extended later on).
• Network efficient: Eliminates bloated responses (we receive only what we ask for) and decreases the number of requests.
• Updates to the clients (e.g. frontend) can be done in a more independent way: if the frontend needs an extra field, it just needs to update the query, no updates are required in the backend, which is great for themes.
• There are packages providing a bridge between Laravel and GraphQL (https://github.com/rebing/graphql-laravel, https://github.com/nuwave/lighthouse), all of them make use of https://webonyx.github.io.
• GraphQL also addresses deletions/updates/insertions.

Cons

• Once you give super powers to the client, it's better to ensure your server is armored, so it's needed to adopt anti-abuse techniques (there are built-in options).
• Learning curve: considering it's not very popular, people will have to spend some time learning its syntax and how to work with it in the frontend/backend (new bottlenecks/solutions).
• Maintenance: I don't think it will be very fast to adopt it, so it has the risk of ending up as another half-baked way to set/retrieve data competing with the other patterns which are still under work.
• Querying data on the frontend might become tedious (you'll have to specify all the fields you want or create reusable fragments)
• More complex to setup authorization/permissions.
• Due to how it works, perhaps we'll have to be more careful to avoid N+1 queries.
• Specific/complex requests will probably require a custom query (e.g. reports?), but that's fine.
• Some pure HTTP operations don't fit it (e.g. download a file).
• Doesn't follow the basic rules of HTTP (e.g. errors can be returned as 200, caching headers, etc.)

Notes

• As an example of how to structure a GraphQL API, here's the GitHub's reference: https://docs.github.com/en/graphql/reference
• Here's a GraphQL usage sample for Vue (https://apollo.vuejs.org/guide/apollo/queries.html#simple-query)

[jonasraoni]

In general I think GraphQL has a great balance between performance x ergonomics, so I'd definitely start a new project with it.

From a maintenance perspective, I don’t think it makes sense for us to keep a REST + a GraphQL API… This way I consider the introduction of GraphQL should incur in the early deprecation of REST.

The REST API is somehow recent, so I don’t think it will be missed by many, but at the same time I think we should stick to our choices to avoid having an architecture salad across the branches.

Anyway, before making any choice, it will be needed to make some experiments and ensure it fits well.

[NateWr]

Two big questions that need to be answered for me:

1. How is authorization handled? We have pretty complex rules about who can access what, even going down to object properties. For example, a reviewer can access a submission record but not details about its title or authors. I imagine it would get very complex to authorize access to a query that could potentially request any data. A REST API at least lets us constrain the potential objects to be authorized to a particular scope, or split authorization rules into different endpoints.
2. Our biggest problem with third-party libraries that involve entity specification is our multilingual data. We had to build custom handling of this in our existing schema system. Can the libraries we'd consider using support an object with dynamic keys like below?

{
  "title": {
    "any_key": <a defined type>
  }
}

[jonasraoni]

1. GraphQL is granular enough to control access to specific fields, here you can see a naive implementation in JavaScript: https://graphql.org/learn/authorization/.

End-users are limited to navigate through the paths and data that we provide, they can't ask for extra fields, make links nor filter/search data without our help, therefore we just need to add guards to the "links" of the graph.

As the key concept of GraphQL revolves around reusing/linking field resolvers, if you have too many edge cases, it will require a good organization to avoid creating a spaguetti of non-related conditions 😅

The tools that we've got to feed the resolvers are:

• Passing down information to the sub-resolvers (e.g. canViewXYZ, callback, ...)
• Passing information through the GraphQL context (it's like a global variable which keeps state)
• An interface allows you to define a type resolver, then if you resolve a Submission into a PublishedSubmission or NewSubmission type, it might be helpful to define distinct permission rules and accessible fields
• Creating custom queries/types (e.g. AnonymousAuthor, could be an User with its name/email wiped off)

2. Yes, GraphQL allows you to specify arguments to any input/output field, so we could have a query like { author { fullName(locale: en_US, familyFirst: true) } }

[marcbria]

My thoughts about this are more or less pointed in your initial post Jonas.

Maintenance: I don't think it will be very fast to adopt it, so it has the risk of ending up as another half-baked way to set/retrieve data competing with the other patterns which are still under work.
Due to how it works, perhaps we'll have to be more careful to avoid N+1 queries.

May be (as sysops) my perspective is biased, but my main concerns will be related with maintenance and performance issues.

It sounds like a "nice to have" feature with a big potential... but IMHO, it won't be in the top the community priority list.

[jonasraoni]

I agree, as it's not a requirement, I'd say it's something that we can experiment if we get some free time/no urgent tasks to handle :)

[jonasraoni]

Looks like GitHub decided to drop some GraphQL APIs in favour of their REST one. I didn't see a reason, but I guess it's too complex to optimize things, while keeping the GraphQL ideals (reusability) intact for a large amount of users 😁

[NateWr]

A friend spoke highly of PostGraphile, a node-based tool that produces a graphql API from a postgres database. It's not appropriate for our general community (node, postgres), but may provide an easy way for a technical team to get graphql access to OJS/OMP/OPS data, when they want to be able to read data into a third-party tool.

[jardakotesovec]

Hi,

Just to drop my 2 cents here as long time graphql user.

I am early graphql adopter.. used it on production projects for last 7 years. And I have mostly good things to say about it. More challenging parts for OJS context would be extending schema runtime (teoretically doable.. but simply not usual use case so that would need to be investigated) and any updates (POST, PUTs) are done via graphql mutations which can provide the same level of capability, but are certainly more difficult to consumers to write such queries correctly compared to REST. And than general challenge with graphql is to stay performant even for very creative queries coming from consumers.

Overall it probably could do good service.. but of course not solving all our problems :-).

Given that we already have decent number of REST endpoints and laravel has much more internal support for creating REST, than graphql. I think sticking with REST is reasonable. If someone would be interested for deeper debate let me know.