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" -->