Skip to content

Commit

Permalink
update api documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@zhouji2013
zhouji2013 committed Oct 7, 2022
1 parent 7b694cb commit 7f3719d
Show file tree
Hide file tree
Showing 2 changed files with 220 additions and 4 deletions.
224 changes: 220 additions & 4 deletions web/src/main/webapp/api-doc.html
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,235 @@
<html>

<div class=container style=padding:20px>
<h2>Dashboard API Documention</h2>
<h2>CTD² Dashboard API</h2>
<p>
<a onclick='document.getElementById("hierarchy").scrollIntoView()'>Dashboard content hierarchy</a>
<ul>
<li><a onclick='document.getElementById("centers").scrollIntoView()'>Centers</a></li>
<li><a onclick='document.getElementById("submissions").scrollIntoView()'>Submissions</a></li>
<li><a onclick='document.getElementById("observations").scrollIntoView()'>Observations</a></li>
<li><a onclick='document.getElementById("observation-summary").scrollIntoView()'>Observation summary</a></li>
</ul>
<a onclick='document.getElementById("api").scrollIntoView()'>Dashboard API calls</a>
<ul>
<li><a onclick='document.getElementById("api-centers").scrollIntoView()'>GET /centers - returns a list of centers</a></li>
<li><a onclick='document.getElementById("api-submission").scrollIntoView()'>GET /submission/{submissionId} - returns content of a submission</a></li>
<li><a onclick='document.getElementById("api-browse").scrollIntoView()'>GET /browse/{subjectClass}/{subjectName} - returns observations for a subject</a></li>
<li><a onclick='document.getElementById("api-search").scrollIntoView()'>GET /search/{term} - search Dashboard</a></li>
<li><a onclick='document.getElementById("api-observation").scrollIntoView()'>GET /observation/{observationId} - returns an observation</a></li>
<li><a onclick='document.getElementById("api-observations").scrollIntoView()'>GET /observations/{submissionId}/{indexRanges} - returns observations from a submission</a></li>
</ul>
</p>
<p>We have designed and implemented the Dashboard API as an alternative route to access the content of the CTD²
Dashboard. The Dashboard data has a hierarchical structure with submission centers - members of the CTD² network
Dashboard. The Dashboard data has a hierarchical structure with submission Centers - members of the CTD² Network
-
at the top. At the next levels, each center provides multiple submissions to the Dashboard and each submission
at the top. At the next level, each Center provides multiple submissions to the Dashboard and each submission
consists of one or more observations. Finally, at the bottom, each observation ties together various biological
entities (subjects) and associated evidence fields. The Dashboard API allows clients to access data at any level
of
the hierarchy. The full specification is available in Dashboard’s GitHub repository
(<a href="https://github.com/CBIIT/nci-ctd2-dashboard/blob/master/web/src/test/CTD2-Dashboard_API.yml"
target=_blank>https://github.com/CBIIT/nci-ctd2-dashboard/blob/master/web/src/test/CTD2-Dashboard_API.yml</a>)
and can be easily browsed by pasting it to a swagger editor at <a href="https://editor.swagger.io/"
target=_blank>https://editor.swagger.io/</a></p>
target=_blank>https://editor.swagger.io/</a>.
</p>
<h3 id="hierarchy">Dashboard content hierarchy</h3>
<h4 id="centers">Centers <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>Centers are the research teams that participate in the CTD2 Network. They are the entities who submit the data, thus each submission is associated with a specific Center responsible for a submission even when multiple Centers contributed to the submission.</p>
<h4 id="submissions">Submissions <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>A submission is a collection of related observations from a participating CTD2 Network Center, sharing the same structure and format, and representing findings from one or more experimental and/or computational investigations. Each submission can comprise multiple observations described using a submission-specific spreadsheet template, with each row corresponding to one observation and columns representing the data elements necessary for fully documenting an observation. Submissions can be assigned to one of three tiers, depending on their level of experimental support. Tier 1 typically represents preliminary results of a screening campaign or large-scale computational analysis. Tier 2 indicates a confirmation of primary results in a cancer-relevant in vitro model. Finally, Tier 3 provides validation obtained in a cancer-relevant in vivo model. A further component of the submission is the “observation summary”.This is a short statement that summarizes the observation in a readable form, appropriate for human consumption. This observation summary is discussed further below. Some submissions may also be associated with a Dashboard “story”, a hypertext narrative with more details describing an in-depth observation.</p>
<h4>Projects</h4>
<p>Each submission is also associated with a single project that represents a research area. Multiple submissions can be associated with a single project.</p>
<h4 id="observations">Observations <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>Observations are the main unit of knowledge in the Dashboard. They are statements describing biological components (e.g., genes, cell lines, compounds) dubbed “subjects” and the roles they play (e.g., target, background, candidate drug) in the context of a high-level investigational finding, along with links to the computational and/or experimental evidence that support this finding.</p>
<p>Subjects are the primary biological entities involved in the experimental and/or computational finding described by an observation. Within an observation, subjects are defined by their class and role. The subject class specifies the type of biological entity and can assume any among a predefined set of choices, namely: gene, shRNA, protein, cell sample, animal model, tissue sample, or compound. Subjects can also have an associated role which further specifies their semantics in the context of an observation; e.g., in an observation from a compound screening experiment, a gene may be assigned the role of a “target” if it is the target of a screened compound; or the role of “biomarker” if it is a determinant of the cell line used for the screen. Subjects assume values from controlled vocabularies, depending on their class.</p>
<p>Observations can also have evidence fields which capture supporting quantitative and qualitative data that are important in interpreting a finding (e.g., details of the experimental or computational protocol used). Each evidence field is characterized by a type and a role. The type is drawn from a fixed set of options (URL, label, data numeric, and file). Possible roles are literature, measured, link, reference, background, observed, computed, written, resources, and species. At the level of the observation, evidence assumes a value, albeit less constrained than for subjects, i.e., evidence values do not usually come from controlled vocabularies.</p>
<figure>
<img src="figure1_object.png" alt="" width="100%">
<figcaption>Figure 1: Schematic representation of Dashboard data structure.</figcaption>
</figure>

<h4 id="observation-summary">Observation summary <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>The observation summary is a short, human-readable statement of an individual finding (an observation) in the Dashboard. As the initial result of most Dashboard queries, it is the main route to quickly understanding the observations. The summary is constructed using a template which is part of each submission and applies to all observations within that submission. The template consists of one or more sentences which contain references to specific columns in the associated observation template (as described above). For any given single observation, the referenced items in the observation summary are filled in with the actual values from that observation. For example, in the submission described above, the observation summary template is:</p>
<blockquote>“Predicted cell-line-specific synthetic lethality of &lt;gene_1&gt; and &lt;gene_2&gt; was tested in &lt;tissue_1&gt; cell line &lt;cell_line_1&gt; by MTT assay using inhibitors &lt;compound_1&gt; and &lt;compound_2&gt; with result: &lt;effect_1&gt;”,</blockquote>
<p>where the column names are enclosed in angle brackets <>. The final displayed text on the web page for the first observation in that submission is</p>
<blockquote>“Short-term cell-viability (MTT) assay of synthetic lethality of <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#gene/h/egfr">EGFR</a> and <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#gene/h/met">MET</a> was tested in <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#tissue/c3512">lung adenocarcinoma</a> cell line <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#cell-sample/calu3">CALU3</a> using inhibitors <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#compound/erlotinib">erlotinib</a> and <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#compound/crizotinib">crizotinib</a> with result: <b>strongly synergistic</b>”.</blockquote>
<p>Note that subject values are hyperlinked on the web page, while evidence values are shown in bold.</p>
<p>The final observation summary text, but without the hyperlinks or bolding, is included in the data returned for each observation by the API. Observations are returned when executing API calls of type “submission”, “browse”, or “search”.</p>
<h3 id="api">Dashboard API calls</h3>
<h4 id="api-centers">GET /centers - returns a list of centers <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>example: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/api/centers">https://ctd2-dashboard.nci.nih.gov/dashboard/api/centers</a></p>
<p>output structure:</p>
<pre>[
{
"center_name": "string",
"center_id": "string",
"principal_investigator": "string",
"submissions": [
"string"
]
}
]</pre>
<p>corresponding Dashboard site: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#centers">https://ctd2-dashboard.nci.nih.gov/dashboard/#centers</a></p>
<h4 id="api-submission">GET /submission/{submissionId} - returns contents of a submission <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>required parameter:</p>
<dl><dt>submissionId</dt><dd>The identifier of the requested submission</dd></dl>
<p>optional parameters:</p>
<dl><dt>maximum</dt><dd>The maximum number of observations returned by the query (if not specified, all observations are returned)</dd></dl>
<p>example: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/api/submission/20130426-dfci-ovarian-analysis">https://ctd2-dashboard.nci.nih.gov/dashboard/api/submission/20130426-dfci-ovarian-analysis</a></p>
<p>output structure:</p>
<pre>{
"submission_center": "string",
"submission_name": "string",
"submission_date": "2013-04-26",
"tier": 2,
"project": "string",
"submission_description": "string",
"story_title": "string",
"observation_count": 0,
"observations": [
"string"
]
}</pre>
<p>corresponding Dashboard site: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#submission/20130426-dfci-ovarian-analysis">https://ctd2-dashboard.nci.nih.gov/dashboard/#submission/20130426-dfci-ovarian-analysis</a></p>
<h4 id="api-browse">GET /browse/{subjectClass}/{subjectName} - returns observations for a subject <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>required parameters:</p>
<dl><dt>subjectClass</dt><dd>Available values: AnimalModel, CellSample, Compound, Gene, ShRna, TissueSample, Evidence</dd>
<dt>subjectName</dt><dd>The name of the subject as known by the Dashboard</dd>
</dl>
<p>optional parameters:</p>
<dl><dt>center</dt><dd>Restrict returned observations by a comma-separated list of center ids (Broad, CSHL, Columbia, DFCI, Emory, FHCR1, FHCR2, Stanford, TGRI, UCSD, UCSF1, UCSF2, UTMDA, UTSW)</dd>
<dt>role</dt><dd>Restrict returned observations by a comma-separated list of roles</dd>
<dt>tier</dt><dd>Restrict returned observations by tier(s)</dd>
<dt>maximum</dt><dd>The maximum number of observations returned by the query (if not specified, all observations are returned)</dd>
</dl>
<p>example: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/api/browse/gene/TP53?center=Broad,DFCI&tier=2,3">https://ctd2-dashboard.nci.nih.gov/dashboard/api/browse/gene/TP53?center=Broad,DFCI&tier=2,3</a></p>
<p>output structure:</p>
<pre>{
"class": "string",
"name": "string",
"synonyms": [
"string"
],
"xref": [
{
"source": "string",
"id": "string"
}
],
"roles": [
"string"
],
"observation_count": {
"tier1": 0,
"tier2": 0,
"tier3": 0
},
"observations": [
"string"
]
}</pre>
<p>corresponding Dashboard site: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#gene/h/tp53/biomarker">https://ctd2-dashboard.nci.nih.gov/dashboard/#gene/h/tp53/biomarker</a></p>
<h4 id="api-search">GET /search/{term} - search Dashboard <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>required parameter:</p>
<dl><dt>term</dt><dd>The search term</dd></dl>
<p>optional parameters:</p>
<dl><dt>center</dt><dd>Restrict returned observations by a comma-separated list of center ids (Broad, CSHL, Columbia, DFCI, Emory, FHCR1, FHCR2, Stanford, TGRI, UCSD, UCSF1, UCSF2, UTMDA, UTSW)</dd>
<dt>role</dt><dd>Restrict returned observations by a comma-separated list of roles</dd>
<dt>tier</dt><dd>Restrict returned observations by tier(s)</dd>
<dt>maximum</dt><dd>The maximum number of observations returned by the query (if not specified, all observations are returned)</dd>
</dl>
<p>example: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/api/search/ALL?role=disease&tier=2,3">https://ctd2-dashboard.nci.nih.gov/dashboard/api/search/ALL?role=disease&tier=2,3</a></p>
<p>output structure:</p>
<pre>[
{
"class": "string",
"name": "string",
"synonyms": [
"string"
],
"xref": [
{
"source": "string",
"id": "string"
}
],
"roles": [
"string"
],
"observation_count": {
"tier1": 0,
"tier2": 0,
"tier3": 0
},
"observations": [
"string"
]
}
]</pre>
<p>corresponding Dashboard site: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#search/ALL">https://ctd2-dashboard.nci.nih.gov/dashboard/#search/ALL</a></p>
<h4 id="api-observation">GET /observation/{observationId} - returns an observation <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>required parameter:</p>
<dl><dt>observationId</dt><dd>Id of the requested observation</dd></dl>
<p>example: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/api/observation/20150724-columbia-akt-tall-0">https://ctd2-dashboard.nci.nih.gov/dashboard/api/observation/20150724-columbia-akt-tall-0</a></p>
<p>output structure:</p>
<pre>{
"submission_id": "string",
"observation_summary": "string",
"subject_list": [
{
"class": "string",
"role": "string",
"description": "string",
"name": "string",
"subject_uri": "string"
}
],
"evidence_list": [
{
"class": "label",
"type": "string",
"description": "string",
"value": "string",
"units": "string",
"mime_type": "string"
}
]
}</pre>
<p>corresponding Dashboard site: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/#observation/20150724-columbia-akt-tall-0">https://ctd2-dashboard.nci.nih.gov/dashboard/#observation/20150724-columbia-akt-tall-0</a></p>
<h4 id="api-observations">GET /observations/{submissionId}/{indexRanges} - returns observations from a submission <small>[<a onclick='window.scrollTo(0, 0)'>back to top</a>]</small></h4>
<p>required parameter:</p>
<dl><dt>submissionId</dt><dd>The name of the requested submission</dd>
<dt>indexRanges</dt><dd>Comma-separated list of indexRanges; each indexRange is either a single index or startIndex-endIndex, e.g. 1,3-5,7,9-13</dd>
</dl>
<p>example: <a href="https://ctd2-dashboard.nci.nih.gov/dashboard/api/observations/20130426-dfci-ovarian-analysis/1,3-5,7,9-13">https://ctd2-dashboard.nci.nih.gov/dashboard/api/observations/20130426-dfci-ovarian-analysis/1,3-5,7,9-13</a></p>
<p>output structure:</p>
<pre>[
{
"submission_id": "string",
"observation_summary": "string",
"subject_list": [
{
"class": "string",
"role": "string",
"description": "string",
"name": "string",
"subject_uri": "string"
}
],
"evidence_list": [
{
"class": "label",
"type": "string",
"description": "string",
"value": "string",
"units": "string",
"mime_type": "string"
}
]
}
]</pre>
<p>corresponding Dashboard site: N/A</p>
</div>

</html>
Binary file added web/src/main/webapp/figure1_object.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 7f3719d

Please sign in to comment.