API

The Cell Model Passports API provides access cell model information and associated datasets.

Introduction

The API for the cell model passports is a HTTP REST-API that returns information based on the URL of GET requests. It strictly follows the JSONAPI v1.0 standards to allow consistent, predictable and discoverable access to all available resources. Therefore, all responses will be in JSON-format and will carry the 'application/vnd.api+json' Content-Type header.

The base-url for the API is https://api.cellmodelpassports.sanger.ac.uk

Endpoints

The base-url needs to be supplemented with a suffix (path) to the resource. The base url and path together form the endpoint. All Cell Model Passport API endpoints are listed below.

Please note that the root url ("/") is not a valid endpoint and will thus result in a 404 (Not Found) error.

Model list endpoints

Endpoints that result in a list of models

/models: List of all models
/samples/<sample_id>/models: A list of models that originate from a specific sample
Example: /samples/SIDS00002/models
/patients/<patient_id>/models: A list of models from a particular patient
Example: /patients/SIDP00003/models
/models/by_<mut_type>/<gene_identifier>: A list of models that have a mutation type in a specific gene.
Valid <mut_type>s are 'frameshift', 'snp', 'insertion', 'deletion', 'splice_variant' or 'mutation'. Use 'mutation' to list models with any kind of mutation in the specified gene.
Example: /models/by_snp/BRAF
Example: /models/by_frameshift/TP53
/models/by_<mut_type>/<gene_identifier>/<variant>: A list of models that have a mutation type in a specific protein location in a specific gene.
Example: /models/by_snp/BRAF/V600 - for any model with a BRAF mutation at the V600 location
Example: /models/by_snp/BRAF/V600E - for any model with a BRAF V660E mutation

Single model endpoints

Endpoints that result in a single model

/models/<id>: Example /models/SIDM00003
/models/<source>/<source_id>: Use any identifier that is annotated
The identifier source is case-insensitive, but the identifier is case-sensitive.
Example: /models/cosmic_id/909751
Example: /models/CCLE_ID/769P_KIDNEY

/models/<model_id>/files
/models/<source>/<source_id>/files: View a list of all files attached to a model

Gene List endpoints

Endpoints that show a list genes

/genes: List of all genes in database

/models/<model_id>/datasets/mutations
/models/<source>/<source_id>/datasets/mutations: All mutations for a specific model
Example: /models/SIDM00003/datasets/mutations
Example: /models/COSMIC_ID/905975/datasets/mutations
/models/<model_id>/datasets/cancer_drivers
/models/<source>/<source_id>/datasets/cancer_drivers: Cancer driver mutations for a specific model
/models/<model_id>/datasets/cancer_drivers/by_<category>
/models/<source>/<source_id>/datasets/cancer_drivers/by_<category>: Cancer drivers of a specific model, ranked by how often they occur in a specific <category>.
Example: /models/SIDM00002/datasets/cancer_drivers/by_tissue - shows all drivers for model SIDM00002, ranked by how often they occur in its tissue.

/models/<model_id>/datasets/genecnv
/models/<source>/<source_id>/datasets/genecnv: Gene level CNV of a specific model

Modifiers

There are query parameters that can be appended to any of the endpoint URLs to modify the response. These modifiers apply mainly to list endpoints, and allow control of sorting, filtering, pagination, specifying which fields to return and the inclusion of related resources.

All modifiers can be combined in a single query to request exactly the desired data

Pagination

Applies to: list endpoints

Use the page[size] parameter to change the number of items in a list, use page[number] to specify the page. The default page size is 30. Use page[size]=0to disable pagination.

Examples

/models?page[size]=100: List of models, paginated per 100
/genes?page[size]=1000&page[number]=5: List of genes in default order, showing gene 4001 to 5000

Inclusion of related properties

Applies to: list and single endpoints

With the include query parameter, related resources can be included in a response. Provide a comma-separated list of relations to include.

In addition to the data, links, and jsonapi-fields of a normal response, an additional field 'included' is added to the response, which contains an array or related resources. The relationships-field in the data parameter of the main object(s) now includes a type and id parameter that refers to each item’s related resources. It is possible to include relations of related resources with the .-notation.

Note: included related resources do not benefit from pagination or other modifiers.

Examples

/models?include=files: List of models and include the files
/models/SIDM00003?include=sample.tissue: Include the sample and the sample's tissue for model SIDM00003

Sorting

Use the sort-parameter to change the sorting order of a list. Specify a comma-separated list on the fields to sort by. Default sorting is ascending, use a minus-sign (-) to sort descending on that field.

Sorting can be used on text-fields (alphabetically) or numerical fields, but not on properties of related properties.

Examples

/models/SIDM00003/datasets/genecnv?sort=-abs_copy_number,gistic_score: List all CNV for model SIDM00003, ordered descending by absolute copy number and then ascending by gistic score
/samples?sort=sampling_year: List all samples sorted by sampling year

Sparse fields selection

Applies to: single and list endpoints

Use the fields[resource] parameter to view a limited list of fields. Provide a comma separated list of fields to include. Selecting only the required fields can significantly reduce the size of the response and increase the speed.

Examples

/models?fields[model]=names: List all models, but only show the 'names'-property
/models?include=sample.tissue&fields[sample]=id,tissue&fields[tissue]=name: List all models, include its sample and the samples tissue, but only include the tissue name

Filtering

Applies to: list endpoints

Filtering allows the list endpoint to be filtered on the server. Filtering is very powerful and flexible, but has a verbose syntax. The basic query parameter is as follows: filter=[list of filters]
A single filter in this list is a json object with three fields:
{"name": <field to filter on>,"op": <operator for filtering>,"val": <value for filtering>}

The ‘name’ is the name of the attribute that is being filtered on.
The ‘op’ is the operator. There is a fixed list of valid operators, but availability depends on the field type of the field being filtered on:

Comperators
eq: check if field is equal to something
ne: check if field is not equal to something
gt: check if field is greater than to something
ge: check if field is greater than or equal to something
lt: check if field is less than to something
le: check if field is less than or equal to something
contains: check if field contains a string
like: check if field contains a string
notlike: check if field does not contains a string
ilike: check if field contains a string (case insensitive)
notilike: check if field does not contains a string (case insensitive)
startswith: check if field starts with a string
endswith: check if field ends with a string
in_: check if field is in a list of values
notin_: check if field is not in a list of values
any: used to filter on to many relationships
has: used to filter on to one relationships

Multiple filters can be applied with the 'and', 'or' and 'not' logic combinators.

Usage

All data in the Cell Model Passports is publicly available and individual users are free to use the API for non-commercial use without login or registration. Throttling of requests may be applied to ensure service reliability and fair use.

Third Party Websites or Applications
Administrators of third-party websites that are interested in using the Cell Model Passports API should contact the Passports via depmap@sanger.ac.uk. Direct use of the API in third party websites without prior permission is not permitted.

Commercial Use
Commercial use of the Cell Model Passports API and/or data is not permitted without prior consent. Please contact depmap@sanger.ac.uk to for enquiries.

Educational Use
Use of the Cell Model Passports API for educational purposes is permitted. Educators interested in using the Cell Model Passports API in their teachings are encouraged to contact depmap@sanger.ac.uk - especially if this could result in a high volume of traffic.

Cell Model Passports

Models

User Guides

API

Introduction

Endpoints

Model list endpoints

Single model endpoints

Gene List endpoints

Modifiers

Pagination

Examples

Inclusion of related properties

Examples

Sorting

Examples

Sparse fields selection

Examples

Filtering

Usage

Cell Model Passports

Websites

Contact