Endpoint Types¶
The API for consuming CIViC data can mostly be broken down into two different types of endpoints: index and detail.
Index Endpoints¶
The index endpoints provide high level overview information about a collection of entities all at once and allow a user to page through all the entities in the system. Index endpoints provide two top-level keys in their JSON structure: _meta and records.
Example /genes Request
curl https://civicdb.org/api/genes
Example /genes Response (partial)
{
"_meta": {
"current_page": 1,
"per_page": "1",
"total_pages": 332,
"total_count": 332,
"links": {
"next": "https://v1.civicdb.org/api/genes?count=1&page=2",
"previous": null
}
},
"records": [
{
"id": 1,
"name": "ALK",
"entrez_id": 238,
"description": "ALK amplifications, fusions and mutations have been shown to be driving events in non-small cell lung cancer. While crizontinib has demonstrated efficacy in treating the amplification, mutations in ALK have been shown to confer resistance to current tyrosine kinase inhibitors. Second-generation TKI's have seen varied success in treating these resistant cases, and the HSP90 inhibitor 17-AAG has been shown to be cytostatic in ALK-altered cell lines.",
"flagged": false,
"variants": [
{
"name": "CAD::ALK",
"id": 2769,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "EML4::ALK L1152R",
"id": 307,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "HIP1::ALK I1171N",
"id": 588,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 2
}
},
{
"name": "RANBP2::ALK",
"id": 514,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "EML4::ALK C1156Y",
"id": 6,
"evidence_items": {
"accepted_count": 4,
"rejected_count": 2,
"submitted_count": 7
}
},
{
"name": "EML4::ALK V1180L",
"id": 528,
"evidence_items": {
"accepted_count": 5,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "Exon 4-11 Deletion",
"id": 550,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "Mutation",
"id": 512,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "EML4::ALK",
"id": 5,
"evidence_items": {
"accepted_count": 7,
"rejected_count": 0,
"submitted_count": 1
}
},
{
"name": "EML4::ALK S1206Y",
"id": 172,
"evidence_items": {
"accepted_count": 2,
"rejected_count": 0,
"submitted_count": 2
}
},
{
"name": "EML4::ALK and Amplification",
"id": 170,
"evidence_items": {
"accepted_count": 3,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "CLTC::ALK",
"id": 520,
"evidence_items": {
"accepted_count": 3,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "EML4::ALK e2-e20",
"id": 501,
"evidence_items": {
"accepted_count": 2,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "EML4::ALK e6-e20",
"id": 503,
"evidence_items": {
"accepted_count": 7,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "R1275Q",
"id": 9,
"evidence_items": {
"accepted_count": 6,
"rejected_count": 0,
"submitted_count": 3
}
},
{
"name": "F1245V",
"id": 1295,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 1,
"submitted_count": 0
}
},
{
"name": "Alternative Transcript (ATI)",
"id": 839,
"evidence_items": {
"accepted_count": 2,
"rejected_count": 0,
"submitted_count": 2
}
},
{
"name": "I1171T",
"id": 3371,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "EML4::ALK I1171S",
"id": 589,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 1
}
},
{
"name": "F1174L",
"id": 8,
"evidence_items": {
"accepted_count": 9,
"rejected_count": 0,
"submitted_count": 3
}
},
{
"name": "STRN::ALK",
"id": 2218,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "ALK Fusion G1269A",
"id": 552,
"evidence_items": {
"accepted_count": 4,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "ALK Fusion G1202R",
"id": 171,
"evidence_items": {
"accepted_count": 6,
"rejected_count": 0,
"submitted_count": 3
}
},
{
"name": "ALK Fusion I1171",
"id": 527,
"evidence_items": {
"accepted_count": 7,
"rejected_count": 0,
"submitted_count": 3
}
},
{
"name": "EML4::ALK G1269A",
"id": 308,
"evidence_items": {
"accepted_count": 2,
"rejected_count": 0,
"submitted_count": 6
}
},
{
"name": "EML4::ALK L1196M",
"id": 7,
"evidence_items": {
"accepted_count": 4,
"rejected_count": 0,
"submitted_count": 11
}
},
{
"name": "F1245C",
"id": 549,
"evidence_items": {
"accepted_count": 2,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "EML4::ALK e20-e20",
"id": 500,
"evidence_items": {
"accepted_count": 4,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "Fusion",
"id": 499,
"evidence_items": {
"accepted_count": 31,
"rejected_count": 2,
"submitted_count": 10
}
},
{
"name": "ALK Fusion F1245C",
"id": 551,
"evidence_items": {
"accepted_count": 3,
"rejected_count": 0,
"submitted_count": 0
}
},
{
"name": "EML4::ALK C1156Y-L1198F",
"id": 352,
"evidence_items": {
"accepted_count": 2,
"rejected_count": 0,
"submitted_count": 1
}
},
{
"name": "NPM::ALK",
"id": 513,
"evidence_items": {
"accepted_count": 3,
"rejected_count": 1,
"submitted_count": 0
}
},
{
"name": "EML4::ALK T1151INST",
"id": 173,
"evidence_items": {
"accepted_count": 4,
"rejected_count": 0,
"submitted_count": 1
}
}
],
"aliases": [
"ALK1",
"ALK",
"NBLST3",
"CD246"
],
"updated_at": "2017-03-06T00:00:15.358Z",
"type": "gene"
}
]
}
Meta Attribute¶
As seen to above, the _meta section contains information about the total number of available records, the page size, and provides links to the next and previous page of results. These links can be used to easily traverse all of the records in CIViC. A null entry for next (or previous) indicates that you have reached the end of the collection.
Records Attribute¶
The records section will contain the actual objects requested in the API call (ie: genes, variants or evidence_items)
If you do not wish to use the links in the _meta section, index endpoints also accept manual pagination parameters in the query string:
Example /genes Request with Manual Pagination
curl https://civicdb.org/api/genes?page=2&count=25
Meta Pagination Parameters
Parameter |
Default |
Description |
|---|---|---|
page |
1 |
Which page of results to return |
count |
25 |
How many records to return on a single page |
Detail Endpoints¶
Detail endpoints return the full CIViC record for a single entity, specified explicitly by id. In addition to the high level overview information returned by the index endpoint, this complete record will include information about data provenance, timestamps, and secondary relationships. Unlike the index endpoints, detail endpoints do not have separate _meta and records sections as only a single record is returned.
Example /genes Detail Request
curl https://civicdb.org/api/genes/533
Example /genes Detail Response
{
"id": 533,
"name": "AXL",
"entrez_id": 558,
"description": "",
"flagged": false,
"variants": [
{
"name": "EXPRESSION",
"id": 651,
"evidence_items": {
"accepted_count": 1,
"rejected_count": 0,
"submitted_count": 0
}
}
],
"aliases": [
"AXL",
"UFO",
"Tyro7",
"JTK11",
"ARK"
],
"updated_at": "2015-09-03T20:09:41.304Z",
"type": "gene",
"lifecycle_actions": {},
"sources": [],
"provisional_values": {},
"errors": {}
}