Add documentation to new Web API

[ecerami]

We need to better document the endpoints in the new Web API.

[ecerami]

Top of page should say:

cBioPortal Web AP [Beta]: A web service for supplying JSON formatted data to cBioPortal clients. Please note that this API is currently in beta and subject to change.

Endpoints:

Cancer Types: Get cancer type information, including full name, short name, identifier, and cancer type hierarchy.

Clinical Attributes: Get meta-data regarding clinical attributes associated with a specific study. Meta-data includes display name, description, identifier and data type.

GET /clinical-attributes: Get all clinical attributes. GET /studies/{studyId}/clinical-attributes: Get all clinical attributes in the specified study. GET /studies/{studyId}/clinical-attributes/{clinicalAttributeId}: Get specified clinical attribute.

Clinical Data: Get de-identified clinical data associated with a study, patient or sample.

POST /clinical-data/fetch: Fetch clinical data by patient IDs or sample IDs (all studies) POST /studies/{studyId}/clinical-data/fetch: Fetch clinical data by patient IDs or sample IDs (specific study)

Clinical Events: Get de-identified clinical events associated with a patient, including patient timeline data.

Copy Number Segments: Get copy number segment data.

Discrete Copy Number Alterations: Get discrete copy number alteration data.

Gene Panels: Get gene panel data (only relevant for studies that use gene panels, and not whole exome or whole genome sequencing).

Gene: Get gene information, including Entrez Gene ID, HUGO gene symbol, aliases, cytoband, and chromosome number.

Molecular Data: Get molecular data, e.g. mRNA expression, methylation, protein expression, etc. For mutation data, see the Mutations endpoint.

GET /genetic-profiles/{geneticProfileId}/genetic-data: Get all molecular data in a molecular profile. POST /genetic-profiles/{geneticProfileId}/genetic-data/fetch: Fetch molecular data by sample ID(s).

Molecular Profiles: Get molecular profiles associated with a study. A single study can have multiple molecular profiles, e.g. for copy number alteration, mRNA and mutations.

GET /genetic-profiles: Get all molecular profiles GET /genetic-profiles/{geneticProfileId}: Get molecular profile GET /studies/{studyId}/genetic-profiles: Get all molecular profiles in a study

Mutations: Get mutation or mutation frequency / count data.

GET /genetic-profiles/{geneticProfileId}/mutation-counts: Get mutation counts in a molecular profile by Sample List ID. POST /genetic-profiles/{geneticProfileId}/mutation-counts/fetch Fetch mutation counts in a molecular profile by sample IDs GET /genetic-profiles/{geneticProfileId}/mutations Get mutations in a molecular profile by Sample List ID POST /genetic-profiles/{geneticProfileId}/mutations/fetch Fetch mutations in a molecular profile by sample IDs POST /mutation-counts-by-position/fetch Fetch mutation counts in all studies by gene and position POST /mutations/fetch Fetch mutations in multiple molecular profiles by sample IDs

Patients: Get de-identified or anonymized patient identifiers.

Sample Lists: Get sample lists associated with specific studies. For example, a study may have a set of all samples with a specific histology or stage.

Samples: Get de-identified or anonymized sample identifiers.

Studies: Get studies. All data sets in cBioPortal are associated with a study, e.g. the TCGA Lung Adenocarcinoma study.

[ecerami]

@ersinciftci @jjgao: above are my suggested API doc suggestions. I have also suggested we change genetic to genomic. Can you please review and make any edits?

[ersinciftci]

It looks like this after adding descriptions to controllers, so we decided with @ecerami to not do it because it doesn't look as pretty as the current page. I'll still make the changes in the sub-endpoints.

[jjgao]

@ecerami @ersinciftci The API page from MolecularMatch (https://api.molecularmatch.com/) looks really good. Not sure if we can do the same. I know that they were using Swagger.

[ersinciftci]

@jjgao @ecerami There is a new Swagger 3 supported version of swagger-ui, http://petstore.swagger.io/, which would solve this problem as it shows descriptions in a smaller font, but we need to wait for Springfox library to update to Swagger 3 for this as well.

[ecerami]

@ersinciftci: that looks way better, and I vote for that option!