GraphQL API

RDF Portal provides a GraphQL API that allows developers and researchers to query life science datasets using GraphQL, a widely adopted query language for APIs. The GraphQL API offers an intuitive, schema-driven alternative to SPARQL, making it easier to retrieve structured data from RDF datasets — especially for those familiar with web application development.

Service URL: https://rdfportal.org/grasp

Note: The GraphQL API currently supports a limited set of databases: UniProt, ChEBI, ChEMBL, and MedGen. Additional databases will be added in future updates.

What is GraphQL?

GraphQL is a query language for APIs developed by Facebook (now Meta) in 2012 and released as open source in 2015. Unlike traditional REST APIs where each endpoint returns a fixed data structure, GraphQL allows clients to specify exactly which fields they need in a single request. Key advantages include:

• Request only what you need — Specify the exact fields to retrieve, avoiding over-fetching of unnecessary data.
• Single endpoint — All queries go to one endpoint, rather than requiring different URLs for different resources.
• Nested queries — Retrieve related data across multiple entities in a single query, following relationships between datasets.
• Self-documenting — The schema defines all available types and fields, which can be explored interactively through tools like GraphiQL.

Grasp: GraphQL-to-SPARQL bridge

The GraphQL API on RDF Portal is powered by Grasp, an open-source middleware developed by DBCLS. Grasp acts as a bridge between GraphQL and SPARQL: it receives GraphQL queries from clients, translates them into SPARQL queries, executes them against the RDF Portal’s SPARQL endpoints, and returns the results in the standard GraphQL response format.

This means that users can take advantage of the rich, interlinked RDF datasets on RDF Portal without needing to write SPARQL queries. Grasp handles the translation transparently, including queries that span multiple databases.

For more details on Grasp, see the GitHub repository.

Interactive query interface

The service URL https://rdfportal.org/grasp provides a GraphiQL interface — an interactive, in-browser IDE for writing and executing GraphQL queries. You can explore the schema, write queries with auto-completion, and view results instantly.

Query examples

The following examples demonstrate how to query RDF Portal datasets through the GraphQL API.

Example 1: Basic query — Retrieve MedGen entries

Fetch basic information for specific MedGen entries by their IDs, including linked NCBI Gene identifiers.

query {
  MedGen(id: ["C1835407", "C1835223"]) {
    iri
    id
    label
    ncbigene
  }
}

Example 2: Detailed query — Retrieve all available MedGen fields

Retrieve comprehensive information from MedGen, including descriptions, concept names, definitions, and associated metadata.

query {
  MedGen(id: ["C1835407", "C1835223"]) {
    iri
    id
    label
    ncbigene
    description
    sty
    name_label
    name_source
    name_suppress
    mgdef_description
    mgdef_source
    mgdef_suppress
    mgconso_aui
    mgconso_ispref
    mgconso_stt
    mgconso_ts
    mgconso_label
    mgconso_source
    mgconso_suppress
    mgsat_metaui
    mgsat_stype
    mgsat_identifier
    mgsat_source
    mgsat_value
    mgsat_label
    mgsat_suppress
  }
}

Example 3: ClinVar query — Retrieve variant information

Fetch clinical variant data from ClinVar, including accession numbers, submission counts, review status, and species.

query {
  ClinVar(id: "5378") {
    iri
    label
    accession
    submissions
    status
    species
  }
}

Example 4: UniProt query — Retrieve protein details

Retrieve detailed protein information from UniProt, including gene name, enzyme classification, sequence, and functional annotations.

query {
  UniProt(id: "Q94KE2") {
    label
    mnemonic
    existence
    gene_name
    ec
    sequence
    function
    affinity
    activity
    kinetics
    ph_dependence
  }
}

Example 5: Nested query — UniProt with linked databases

One of GraphQL’s strengths is the ability to follow relationships in a single query. This example retrieves a UniProt protein entry along with its linked ChEBI compounds, Gene Ontology (GO) annotations, and HGNC gene information.

query {
  UniProt(id: "Q94KE2") {
    label
    mnemonic
    existence
    gene_name
    ec
    sequence
    function
    affinity
    activity
    kinetics
    ph_dependence
    ChEBI {
      formula
    }
    GO {
      id
      label
      namespace
    }
    HGNC {
      id
      label
      description
      location
    }
  }
}

Example 6: Cross-database query — ChEMBL with linked ChEBI and UniProt

This example demonstrates a cross-database query starting from a ChEMBL compound. It retrieves the compound’s chemical properties and drug development information, along with linked ChEBI identifiers and UniProt protein targets.

query {
  ChEMBL(id: "CHEMBL941") {
    label
    smiles
    atc
    alogp
    drug_development_phase
    pchembl
    ChEBI {
      id
      charge
    }
    UniProt {
      mnemonic
      label
      organism
    }
  }
}

Programmatic access

You can also send GraphQL queries programmatically. For example, using curl:

curl -X POST https://rdfportal.org/grasp \
  -H "Content-Type: application/json" \
  -d '{"query": "{ UniProt(id: \"Q94KE2\") { label mnemonic gene_name } }"}'

Or using Python with the requests library:

import requests

query = """
{
  UniProt(id: "Q94KE2") {
    label
    mnemonic
    gene_name
    ec
  }
}
"""

response = requests.post(
    "https://rdfportal.org/grasp",
    json={"query": query}
)
print(response.json())