API Documentation
This document describes how to interact with Mitopaths through the search API mechanism. Data about molecules, proteins and pathways can be automatically retrieved by using the freely available API, which responds to HTTP GET requests by sending a simple JSON document with the requested information.
API is available at /API/search, and requires the following parameters:
- q: query string used for search (can be a protein/pathway name, piece of name, etc), or * (star) to retrieve all of the information
and accepts the following optional parameters:
- filters: array of filters (see dedicated section)
- page: page number, for pagination (deafult: 0)
- page_size: page size, for pagination (default: 10)
Filter API
Filters allow returning only results matching a specific criterion, for instance only proteins or only pathways. To specify conjunctive filters it is enough to place multiple copies of the parameter in the query string:
/API/search?q=*&filters[]=type:pathway&filters[]=category:"Energy+Metabolism"
It is also possible to specify disjunctive filters by using OR:
/API/search?q=*&filters[]=type:(pathway+OR+protein)
Mitopaths uses the Lucene Syntax, which serves as a comprehensive guide about how to structure queries.
Response Format
Response is a JSON defining the following fields:
- q: query string requested by the client
- results: number of results
- page: page number, for pagination
- page_size: number of items per page, for pagination
- items: array of matching items (see details below)
- facet_fields: dictionary of facets, used as statistical information of for filtering (see details below)
Items Format
Attributes in an item depend on the type of item. Every items share the following fields:
- id: Mitopaths identifier
- name: name of the protein/pathway
- type: type of item, one of molecule, protein, mutated_protein, pathway, mutated_pathway
- description: textual description provided by the editor
Pathways and deregulated pathways also define the following attributes:
- theorem: main theorem, in Z-syntax (right arrow symbol is encoded as rArr)
- steps: array of demonstrative and biological steps, each one written in Z-syntax
- category: array of names of categories/mitochondrial processes to which the pathway belongs
Proteins variants also define an original_protein attribute containing the name of the protein they are a mutation of. Similarly, deregulated pathways expose the name of their original_pathway.
Facet Fields
Mitopaths search API also returns some aggregated information. The facet_fields attribute dictionary defines the following fields:
- type_facet: for every item type (molecule, protein, mutated_protein, pathway, mutated_pathway), the number of matching items of that type
- category_facet: for every category, the number of matching pathways in that category (categories with 0 matching pathways are omitted)
- original_protein_facet: for each protein, the number of its mutations matching the query (omitted for proteins not having a mutation)
- original_pathway_facet: for each pathway (name), the number of mutations (pathways without mutations are omitted)
Some examples
/API/search?q=*&page_size=10&filters[]=type:(protein+OR+pathway)
Matches every protein and every pathway, returns first 10 elements:
{
"q": "*",
"response_time": 19,
"results": 90,
"page": 0,
"page_size": 10,
"items": [
{
"id": "protein_0463a1dad13580695be3ac791f533ffb",
"name": "AFG3L2",
"type": "protein",
"description": "AFG3-like protein 2",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:Q9Y4W6"
],
"_highlighting": []
},
{
"id": "protein_6a6cd719ce54c3a00d3f4e862a39373a",
"name": "Bax",
"type": "protein",
"description": "Apoptosis regulator BAX\r\n",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:Q07812"
],
"_highlighting": []
},
{
"id": "protein_21679e33cc9b0e290a6401f1b8569d43",
"name": "Bcl-Xl",
"type": "protein",
"description": "Bcl-2-like protein 1",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:Q07817"
],
"_highlighting": []
},
{
"id": "protein_7b7f6b6a3c8b116e66b92d0b18780e4f",
"name": "BCS1L",
"type": "protein",
"description": "Mitochondrial chaperone BCS1",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:Q9Y276"
],
"_highlighting": []
},
{
"id": "protein_e6ebc89461d5461dfec291971b4fc9fc",
"name": "CCDC109B",
"type": "protein",
"description": "Calcium uniporter regulatory subunit MCUb, mitochondrial",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:Q9NWR8"
],
"_highlighting": []
},
{
"id": "protein_5d729cdf1147cb8c75db57bafd85d181",
"name": "CHCHD4",
"type": "protein",
"description": "Mitochondrial intermembrane space import and assembly protein 40",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:Q8N4Q1"
],
"_highlighting": []
},
{
"id": "protein_b63076c96b71d1a01717b23322a90f6d",
"name": "COX4I1",
"type": "protein",
"description": "Cytochrome c oxidase subunit 4 isoform 1, mitochondrial",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:P13073"
],
"_highlighting": []
},
{
"id": "protein_12101ce033797f8ec6713a71980bf47e",
"name": "CYC1",
"type": "protein",
"description": "Cytochrome c1, heme protein, mitochondrial",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:P08574"
],
"_highlighting": []
},
{
"id": "protein_f505858a409290e352e4b3ad9ca8918e",
"name": "CYCS",
"type": "protein",
"description": "Cytochrome c",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:P99999"
],
"_highlighting": []
},
{
"id": "protein_de8ea752543acd6088750e2e11bffff9",
"name": "CYTB",
"type": "protein",
"description": "Cytochrome b",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:P00156"
],
"_highlighting": []
}
],
"facet_fields": {
"type_facet": {
"protein": 69,
"pathway": 21,
"category": 0,
"molecule": 0,
"mutated_pathway": 0,
"mutated_protein": 0
},
"category_facet": {
"Ca2+ signalling": 5,
"Transport of small molecules": 5,
"Energy Metabolism": 3,
"Ions exchange": 3,
"Mitophagy": 3,
"Antioxidant system": 2,
"Apoptosis": 2,
"Fusion/Fission": 2,
"Oxidative phosphorylation": 2,
"Protein Translocation": 2,
"Protein turnover": 2,
"ROS homeostasis": 2
},
"original_protein_facet": {
"MFN2": 0,
"PARK6": 0
},
"original_pathway_facet": {
"MFN2 homo-oligomerization": 0
}
}
}
/API/search?q=MFN2
Searhces for MFN2, hence both the molecule and the pathways containing it:
{
"q": "MFN2",
"response_time": 31,
"results": 6,
"page": 0,
"page_size": 10,
"items": [
{
"id": "protein_b02f8550e05f4c407fae663bc7e7d572",
"name": "MFN2",
"type": "protein",
"description": "Mitofusin-2",
"geneontology link_attr": [
"http://amigo.geneontology.org/amigo/gene_product/UniProtKB:O95140"
],
"_highlighting": {
"name": [
"MFN2"
]
}
},
{
"id": "pathway_ba74f024c19ea75245338d760a41c0fc",
"name": "MFN1-MFN2 oligomerization",
"type": "pathway",
"theorem": "MFN1 & MFN2 & GTP & GTP ⇒ (MFN1 * MFN2)",
"steps": [
"MFN1 & MFN2 & GTP & GTP ⇒ (MFN1 * GTP) & (MFN2 * GTP)",
"(MFN1 * GTP) & (MFN2 * GTP) ⇒ (MFN1 * Pi) & (MFN2 * Pi) & GDP & GDP",
"(MFN1 * Pi) & (MFN2 * Pi) ⇒ (MFN1 * MFN2)"
],
"category": [
"Fusion/Fission"
],
"_highlighting": {
"name": [
"MFN1-MFN2 oligomerization"
],
"theorem": [
"MFN1 & MFN2 & GTP & GTP ⇒ (MFN1 * MFN2)"
],
"steps": [
"MFN1 & MFN2 & GTP & GTP ⇒ (MFN1 * GTP) & (MFN2 * GTP)",
"(MFN1 * GTP) & (MFN2 * GTP) ⇒ (MFN1 * Pi) & (MFN2 * Pi) & GDP & GDP",
"(MFN1 * Pi) & (MFN2 * Pi) ⇒ (MFN1 * MFN2)"
]
}
},
{
"id": "pathway_ddfc5c7957769e76ac791e350780f315",
"name": "MFN2 homo-oligomerization",
"type": "pathway",
"theorem": "MFN2 & MFN2 & GTP & GTP ⇒ (MFN2 * MFN2)",
"steps": [
"MFN2 & MFN2 & GTP & GTP ⇒ (MFN2 * GTP) & (MFN2 * GTP)",
"(MFN2 * GTP) ⇒ (MFN2 * Pi) & (MFN2 * Pi) & GDP & GDP",
"(MFN2 * Pi) & (MFN2 * Pi) ⇒ (MFN2 * MFN2)"
],
"category": [
"Fusion/Fission"
],
"_highlighting": {
"name": [
"MFN2 homo-oligomerization"
],
"theorem": [
"MFN2 & MFN2 & GTP & GTP ⇒ (MFN2 * MFN2)"
],
"steps": [
"MFN2 & MFN2 & GTP & GTP ⇒ (MFN2 * GTP) & (MFN2 * GTP)",
"(MFN2 * GTP) ⇒ (MFN2 * Pi) & (MFN2 * Pi) & GDP & GDP",
"(MFN2 * Pi) & (MFN2 * Pi) ⇒ (MFN2 * MFN2)"
]
}
},
{
"id": "mutated_pathway_9611ef89f7380e2266da80294ab711b9",
"name": "Reduced MFN2 activity",
"type": "mutated_pathway",
"original_pathway": "MFN2 homo-oligomerization",
"theorem": "R707WMFN2 & R707WMFN2 & GTP & GTP ⇒ R707WMFN2 & R707WMFN2 & GTP & GTP",
"steps": [
"R707WMFN2 & R707WMFN2 & GTP & GTP ⇒ (R707WMFN2 * GTP) & (R707WMFN2 * GTP)",
"(R707WMFN2 * GTP) & (R707WMFN2 * GTP) ⇒ R707WMFN2 & R707WMFN2 & GTP & GTP"
],
"category": [
"Fusion/Fission"
],
"_highlighting": {
"name": [
"Reduced MFN2 activity"
],
"original_pathway": [
"MFN2 homo-oligomerization"
]
}
},
{
"id": "mutated_protein_b1d72ede0f0676eb17176d492845706d",
"name": "R707WMFN2",
"type": "mutated_protein",
"original_protein": "MFN2",
"description": "Missense mutation R -> W",
"_highlighting": {
"original_protein": [
"MFN2"
]
}
},
{
"id": "pathway_7e30b86e96a688b886846b252acb2090",
"name": "MFNs-mediated mitophagy",
"type": "pathway",
"theorem": "PARK6 & PARK6 & TOMM40 & Phos & Phos & Phos & PRKN & UBE2s & UBE2s & (MFN1 * MFN2) & SQSTM1 & MAP1LC3A ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s * SQSTM1 * MAP1LC3A)",
"steps": [
"PARK6 & PARK6 ⇒ (PARK6 * PARK6)",
"(PARK6 * PARK6) & TOMM40 ⇒ (PARK6 * PARK6 * TOMM40)",
"(PARK6 * PARK6 * TOMM40) & Phos & Phos ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & PRKN ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & PRKN",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & PRKN & Phos ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & UBE2s & (MFN1 * MFN2) ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & ((Phos * PRKN) * UBE2s) & (MFN1 * MFN2)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & ((Phos * PRKN) * UBE2s) & (MFN1 * MFN2) ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s) & UBE2s ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s) & SQSTM1 ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s * SQSTM1)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s * SQSTM1) & MAP1LC3A ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s * SQSTM1 * MAP1LC3A)"
],
"category": [
"Mitophagy"
],
"_highlighting": {
"theorem": [
"PARK6 & PARK6 & TOMM40 & Phos & Phos & Phos & PRKN & UBE2s & UBE2s & (MFN1 * MFN2) & SQSTM1 & MAP1LC3A ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s * SQSTM1 * MAP1LC3A)"
],
"steps": [
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & UBE2s & (MFN1 * MFN2) ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & ((Phos * PRKN) * UBE2s) & (MFN1 * MFN2)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & ((Phos * PRKN) * UBE2s) & (MFN1 * MFN2) ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s) & UBE2s ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s) & SQSTM1 ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s * SQSTM1)",
"((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s * SQSTM1) & MAP1LC3A ⇒ ((Phos * PARK6) * (Phos * PARK6) * TOMM40) & (Phos * PRKN) & (MFN1 * MFN2 * UBE2s * UBE2s * SQSTM1 * MAP1LC3A)"
]
}
}
],
"facet_fields": {
"type_facet": {
"pathway": 3,
"mutated_pathway": 1,
"mutated_protein": 1,
"protein": 1,
"category": 0,
"molecule": 0
},
"category_facet": {
"Fusion/Fission": 3,
"Mitophagy": 1,
"Antioxidant system": 0,
"Apoptosis": 0,
"Ca2+ signalling": 0,
"Energy Metabolism": 0,
"Ions exchange": 0,
"Oxidative phosphorylation": 0,
"Protein Translocation": 0,
"Protein turnover": 0,
"ROS homeostasis": 0,
"Transport of small molecules": 0
},
"original_protein_facet": {
"MFN2": 1,
"PARK6": 0
},
"original_pathway_facet": {
"MFN2 homo-oligomerization": 1
}
}
}