Best practice for registering GraphQL with SmartAPI

[cmungall]

What is the best practice for registering graphql APIs? This is a different framework than OpenAPI (see any number of blog posts). There are converters, but there is a big impedance mismatch between the frameworks meaning any automated conversion will likely be unsatisfactory.

For example, using https://github.com/yarax/swagger-to-graphql on MyChem.info

$ curl http://smart-api.info/api/metadata/8f08d1446e0bb9c2b323713ce83e2bd3 > mychem.json
$ swagger-to-graphql --swagger mychem.json 
type get_drug_drugid {
  # default field
  empty: String
}

type get_query {
  # default field
  empty: String
}

# DrugBank ID, InCHIKey, CHEBI ID, CHEMBL ID
input param_get_drug_drugid_drugid {
  # default field
  empty: String
}

# Query string. Examples "Fludara", "CHEMBI:63599", "DB01073".
input param_get_query_q {
  # default field
  empty: String
}

type Query {
  viewer: viewer
}

type viewer {
  get_query(q: param_get_query_q): get_query
  get_drug_drugid(drugid: param_get_drug_drugid_drugid): get_drug_drugid
}

it's not clear what the best practice should be. Should we create a stub entry for the main graphql path? What is the best way of pointing to the garphql schema?

[micheldumontier]

well, if i understand correctly, we probably want to go the other direction, from a graphql description to a smartAPI description.

[micheldumontier]

does graphql express the data schema as json schema? if so, then you can use the $ref to point to that schema doc.

on the input side, given that graphql is its own query language, you can point to its use through the externalValue of example objects in the openAPI spec:

https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#exampleObject

would that work?

[cmungall]

Yes, we do want to go in the other direction, I was using swagger-to-graphql as an example as it came up in the dcppc ticket, and it illustrates the large impedance mismatch. The opposite direction will be harder due to the flexibility of graphql. We could use the approach of pre-generating paths but that defines the entire purpose of graphql.

re json schema: graphql schemas are different from json schema. There are components that are directly mappable, but others that can't. Also, the final structure is determined based on the user's query, so mapping of the IDL to json-schema won't necessarily help.

I think including links using the mechanism you specify will be a help. But most of the semantics of graphql will remain opaque. Perhaps this is fine for the purposes of creating a stub entry and letting a human user follow links to more information. But it seems the goals of smartAPI are more ambitious than allowing for search over simple metadata stubs.

I think smartAPI made a good decision in deciding on OpenAPI, as this is undoubtedly the standard for REST-like RPC APIs. But it's not clear that all web-based ways of accessing information will be REST-like RPC APIs. It remains to be seen where GraphQL is on the hype cycle, but there are important bioinformatics databases like gnomad that use it and the absence of entries for these is conspicuous. Perhaps OpenAPI v4 will address this.

Longer term, I wonder if if something like Hydra may provide a more flexible mechanism (cc @RubenVerborgh). It is less pinned to an individual framework like OpenAPI, and works well for Semantic Hypermedia APIs (which can somewhat be described by OpenAPI, but is a bit less than satisfactory).

In the short term I think we need some standard way of getting at least stubs for graphql services in. I think we may want to make smartAPI more flexible and add specific fields for things like the graphql schema.

[micheldumontier]

can we not register any kind of web API, including graphql apis (as they use HTTP GET), with a minimal smartAPI description e.g.
https://gist.github.com/micheldumontier/ba7c1791bcfceb6e39504e92c229b8af

-> feel free to suggest changes to this minimal markup!

anyways, what about this: https://github.com/graphql/express-graphql

[stevencox]

this approach is mostly complementary to the minimal markup above. It provides a bit of automation for extracting the schema of a GraphQL API, populates desirable smartAPI tags, throws in some modularity, and so on. But at the end of the day, they're similar. Also, the GET url for a GraphQL query is impossible to read and would be hard to maintain.

On the SPARQL front, there's Grlc which generates Swagger APIs from GitHub repos of SPARQL queries. One could imagine modding that to smartAPI-ify the output.

[newgene]

I'm pretty sure you can already register a Graphql endpoint as a regular SmartAPI entry, as least as the first step. It's a single http endpoint anyway. Whether we should include extra metadata in SmartAPI specs or not, that should be driven by how the downstream application is going to use it, e.g. how you want a graphql to work together with other REST APIs or another graphql endpoint.

I could be wrong here, but I imagine graphql is self-contained, SmartAPI probably just need to label it as "graphql" type API, that is. The downstream application should know how to get the schema and how to make the queries.

That is like saying if all REST APIs have a "standard" way to describe their data schema, we should not need to put the schema into the SmartAPI specs. In reality, there is no standard for REST APIs, that's why SmartAPI is needed.

[stevencox]

Updated and added the spec we looked at as a prototype of GraphQL registry metadata at the hackathon. Here's client code that would invoke the service based on the registry metadata.