Page MenuHomePhabricator

[Timebox 16 hours] Investigate and document GraphQL endpoint v REST API endpoints for new functionality
Closed, ResolvedPublic

Description

Based on the work done in the WDQS classification, the top functionality that should be moved out is as follows -

  • Bulk GET (getting data of multiple items in a single request)
  • Inverse look up, i.e. finding items (subjects) by statement property (predicate) and statement value (object) (for the sake of this ticket, take faceted search as a whole)
  • Labels of linked entities

In order to make a decision on whether to build these in a GraphQL endpoint vs as additional endpoints in the Wikibase REST API, please draft a document listing the advantages and disadvantages of each.

Some questions that we should look into:

  1. For the user, would using one GraphQL endpoint with the different functionalities be better developer experience or multiple REST API endpoints?
  2. How feasible and maintainable is one over another? Would one be more performant? How would fit within the exisiting infrastructure?
  3. How much work would it be to bring in a new technology (GraphQL) [Ideally we'll check if this was also historically tried and why it didn't pan out]
  4. How much development time would one take over another?
  5. Would we have an internal preference?
  6. Are there mitigations for the trade offs of one over another?

Event Timeline

Ifrahkhanyaree_WMDE renamed this task from [WIP!] [Epic] Bulk GET to [WIP!] Prototype GraphQL endpoint.Jun 16 2025, 8:46 AM
Ifrahkhanyaree_WMDE updated the task description. (Show Details)
Ifrahkhanyaree_WMDE renamed this task from [WIP!] Prototype GraphQL endpoint to Document GraphQL endpoint v REST API endpoints for new functionality.Jun 16 2025, 7:25 PM
Ifrahkhanyaree_WMDE updated the task description. (Show Details)
Ifrahkhanyaree_WMDE moved this task from Backlog to To polish on the Wikibase Reuse Team board.
Ifrahkhanyaree_WMDE renamed this task from Document GraphQL endpoint v REST API endpoints for new functionality to [Timebox 16 hours] Investigate and document GraphQL endpoint v REST API endpoints for new functionality.Jun 24 2025, 9:57 AM

Here is a (late) summary of the investigation. In short:

  • We believe that GraphQL is likely the better user experience
  • GraphQL is more effort to build and maintain
  • We should build a prototype to see what’s technically possible and if it’s worth it (done: T399452)
  • There are not a lot of docs to be found regarding GraphQL adoption in Wikimedia

For the user, would using one GraphQL endpoint with the different functionalities be better developer experience or multiple REST API endpoints?

Gut feeling: GraphQL is the better developer experience.

Arguments in favor of GraphQL:

  • It’s more of a one-stop shop. Users can do e.g. a (faceted) search + get statements + labels of linked entities in a single request. This makes for a better user experience when exploring the data, and also seems to be preferred by many users.
  • It’s very flexible and intuitive when it comes to letting users decide what data they want to request. Even a very polished REST endpoint is going to be more limited in that regard.
  • Tooling is pretty good with libraries like apollo client, and GraphiQL for interactive documentation.

Arguments against GraphQL:

  • It’s not as common as REST APIs, especially in the Wikimedia community, and there is a (small-ish) learning curve.
  • It’s mostly popular in the JS world. Tooling for other languages may not be as good and widely available as for REST APIs.

Considering the different features individually:

  • Getting multiple items/properties at once works equally well in both
  • Faceted search works equally well in both
  • Labels of linked entities is what GraphQL excels at. Flexible data retrieval is what it’s made for.
  • Combining (faceted) search or bulk GET with labels (or any other data\!) of linked entities works well in GraphQL

How feasible and maintainable is one over another? Would one be more performant? How would it fit within the existing infrastructure?

Much of this depends on how we choose to implement the GraphQL solution. The following assumes that we implement them using the same technologies we'd use for the REST API, i.e. PHP and existing databases and services. PHP tooling was explored in T399452 and seems good.

Performance:

  • Doing the same task, performance should be roughly the same. There is nothing inherently more expensive about GraphQL.
  • Due to GraphQLs flexibility we will likely have to enforce some limitations on how many entities can be loaded at a time or how deep we allow requests to be nested.
  • GraphQLs flexible data retrieval means that there is less over-fetching, which in turn means that less data has to travel across the network

Maintainability:

  • GraphQL is more difficult to maintain. We historically tried to narrowly define use cases that map to one or multiple REST routes, but this may not be easily doable for GraphQL. There is a lot of functionality crammed into one endpoint.

Fit within the existing infrastructure:

  • Again, assuming a PHP implementation of a GraphQL endpoint is possible, there should not be any major hurdles. We don’t necessarily need new database technologies or services.