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)
Expecting value: line 1 column 1 (char 0)
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
Expecting value: line 1 column 1 (char 0)