specs

specs copied to clipboard

GraphQL is a big fad nowadays (and http://platform.ontotext.com/ provides GraphQL over RDF data).

Does it have any relevance for the Reconciliation API? I tend to vote no: it could simplify the API use a bit, but it'd have to support the old (REST) API anyway and there is one main client (OpenRefine), so I'd say it's not worth it.

We thought about GraphQL when we added the Data Extension API. I was also reluctant to use it, because it did not fit well with the spirit and data model of the existing API, with simple JSON-based REST endpoints. I also thought it would be harder for services to add support for it, since it would need to rely on relatively large third-party libraries which are not necessarily available in many languages and frameworks. Because GraphQL is very expressive it would also be potentially expensive to run. But that being said if we are to make big breaking changes to the API anyway, it might be worth considering. It could be a nice thing to have if the other parts of the service (reconciliation, suggest, preview, extension) could be recast in a GraphQL flavour too.

@wetneb I'm curious why you thought in particular about Extension. Could you give an example of Extension request/response in REST and GQL (I could do the latter), so we can compare?

Well, the data extension API is all about "returning user-selected properties from some records", which is what GraphQL is all about too, so this is where we saw a connection.

A sample data extension query is here: https://reconciliation-api.github.io/specs/latest/#example-20

This is the analog in GraphQL. The query is simpler (more natural):

query extendData {
 entity (where:{id:{IN:["10662041X","1064905412"]}}) {
   id
   variantName(limit:5)
   geographicAreaCode(limit:1) {id}
   professionOrOccupation {id name}
 }
}

The field params are not standardized. Each service implements its own version of where, and some services use first instead of limit.

The response has exactly the same form as the query, so there's no meta. (The form is not very different from the current example).

{"data":
 {"entity": [
   {"id":"10662041X",
    "variantName": ["Stryi-Leitgeb, Gerda","Leitgeb, Gerda Stryi-"],
    "geographicAreaCode": ["http://d-nb.info/standards/vocab/gnd/geographic-area-code#XA-DE"],
    "professionOrOccupation": [
      {
        "id": "4037223-6",
        "name": "Malerin"
      },
      {
        "id": "4033430-2",
        "name": "Künstlerin"
      }
    ]
   },
   {"id": "1064905412",
    "variantName": [],
    "geographicAreaCode": ["http://d-nb.info/standards/vocab/gnd/geographic-area-code#XA-DE"],
    "professionOrOccupation": [
      {
        "id": "4002844-6",
        "name": "Architekt"
      }
    ]
   }
 ]
}

GraphQL really shines if you fetch nested (related) objects because then you can specify exactly which fields of those objects to get. But people won't use nested objects to populate an OR column...

I think GraphQL would be useful if you want to reconcile or fetch data from mutliple entity types. But that's not the ideology of OR...

What would reconciliation look like with GraphQL? The query above makes sense for data extension, but what about reconciliation itself?

GraphQL queries are typically small and don't usually carry big arrays of data. So I don't see it as a good fit for Recon

#84 discusses breaking API changes to fix REST shortcomings