50d394c587526db4622320a27d85f1e1ef8b9e4f lrnassar Thu May 16 11:12:37 2019 -0700 Adding an additional section with longer examples to api.html #18869 diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html index b8dc50c..10eddad 100755 --- src/hg/htdocs/goldenPath/help/api.html +++ src/hg/htdocs/goldenPath/help/api.html @@ -7,30 +7,31 @@ <h1>JSON API data interface</h1> <h2>Contents</h2> <h6><a href="#Intro">What is JSON data ?</a></h6> <h6><a href="#Access">What is the access URL ?</a></h6> <h6><a href="#Return">What type of data can be accessed ?</a></h6> <h6><a href="#Endpoint">Endpoint functions</a></h6> <h6><a href="#Parameters">Parameters to endpoint functions</a></h6> <h6><a href="#Parameter_use">Required and optional parameters</a></h6> <h6><a href="#Track_types">Supported track types</a></h6> <h6><a href="#list_examples">Example data access, list functions</a></h6> <h6><a href="#getData_examples">Example data access, getData functions</a></h6> <h6><a href="#Error_examples">Error return examples</a></h6> +<h6><a href="#Practical_examples">Practical examples</a></h6> <!-- ========== What is JSON data ? ============================== --> <a id="Intro"></a> <h2>What is JSON data ?</h2> <p> JSON data is a data transfer syntax from a data provider to a data consumer. See also: <a href="https://www.w3schools.com/js/js_json_intro.asp" target=_blank>JSON Introduction</a> </p> <!-- ========== What is the access URL ? ============================== --> <a id="Access"></a> <h2>What is the access URL ?</h2> <p> This access url: <b>https://api.genome.ucsc.edu/</b> is used to access @@ -263,16 +264,59 @@ <p> <ol> <li><a href='https://api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=assembly;chrom=chrI;start=43521;end=54321' target=_blank>Request track data for non-existent chromosome in an assembly hub genome</a> - <br><b>api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=assembly;chrom=chrI;start=43521;end=54321</b></li> <li><a href='https://api.genome.ucsc.edu/getData/track?genome=hg19;track=knownGene' target=_blank>Request track data with over 1M items, return first 1M and flag maxItemsLimit:true</a> - <br><b>api.genome.ucsc.edu/getData/track?genome=hg19;track=knownGene</b></li> <li><a href='https://api.genome.ucsc.edu/getData/track?genome=hg19;track=decipherSnvs' target=_blank>Request track data from a restricted track</a>. See <a href='../../FAQ/FAQdownloads.html#download40' target=_blank>FAQ</a> - <br><b>api.genome.ucsc.edu/getData/track?genome=hg19;track=decipherSnvs</b></li> </ol> </p> +<!-- ========== Practical Examples ======================= --> + +<a id="Practical_examples"></a> +<h2>Practical examples</h2> + +<h3>Looking up the schema of a specific track</h3> + +<p> +When querying track data with the <b>/getData/track</b> function, the <b>jsonOutputArrays</b> +can be used in conjunction to see the track schema. This includes a description of each field +present in the track. The data will also be returned in JSON array type.</p> + +<p> +<a href='https://api.genome.ucsc.edu/getData/track?genome=hg38;track=gold;chrom=chrM;jsonOutputArrays=1' +target=_blank>Request data from hg38 gold track in array type</a> - +<br><b>api.genome.ucsc.edu/getData/track?genome=hg38;track=gold;chrom=chrM;jsonOutputArrays=1</b></p> + +<h3>Hide track container information with trackLeavesOnly parameter</h3> + +<p> +When using the <b>/list/tracks</b> function to see the available tracks in an assembly, it can +be useful to return all tracks in the same hierarchical level. By default, composite and +supertracks will have the subtracks nested below, however, the <b>trackLeavesOnly=1</b> parameter +can be passed to hide the container information, and display all tracks and subtracks at the +same level.</p> + +<p> +In the following example, the first link does not include the trackLeavesOnly parameter. The +output can be compared to the second link to see the difference. This can be observed in the +conservation track. In the first link, the multiz20way track is nested within the cons20way +track. In the second link, however, the multiz20way subtrack is seen at an equivelant level +with all other tracks, and the container, cons20way, is not present in the list.</p> + +<p> +<a href='https://api.genome.ucsc.edu/list/tracks?genome=rn6' +target=_blank>Request available tracks in the rn6 genome</a> - +<br><b>api.genome.ucsc.edu/list/tracks?genome=rn6</b></p> + +<p> +<a href='https://api.genome.ucsc.edu/list/tracks?genome=rn6;trackLeavesOnly=1' +target=_blank>Request available tracks in the rn6 genome, hiding container information</a> - +<br><b>api.genome.ucsc.edu/list/tracks?genome=rn6;trackLeavesOnly=1</b></p> + <!--#include virtual="$ROOT/inc/gbPageEnd.html" -->