Request for comments: GraphQL support

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 (GitHub - rebing/graphql-laravel: Laravel wrapper for Facebook's GraphQL, GitHub - nuwave/lighthouse: A framework for serving GraphQL from Laravel), 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

Best,
Jonas

1 Like

In general I think GraphQL has a great balance between performance x ergonomics.

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 choices, it will be needed to make some experiments and ensure it fits well.

Best,
Jonas

Closing this topic as we’re moving strictly technical discussions into GitHub discussions: GraphQL support · Discussion #7990 · pkp/pkp-lib · GitHub

Best,
Jonas

1 Like