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
- As an example of how to structure a GraphQL API, here’s the GitHub’s reference: Reference - GitHub Docs
- Here’s a GraphQL usage sample for Vue (https://apollo.vuejs.org/guide/apollo/queries.html#simple-query)
Best,
Jonas