f8ec1e5046ba29f263a9483fe00ee7b9da0af206 max Thu Jul 4 08:20:03 2024 -0700 pointing users to other options to get our data in API docs, refs #34045 diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html index 188a380..617b97a 100755 --- src/hg/htdocs/goldenPath/help/api.html +++ src/hg/htdocs/goldenPath/help/api.html @@ -1,56 +1,78 @@ <!DOCTYPE html> <!--#set var="TITLE" value="REST API data interface" --> <!--#set var="ROOT" value="../.." --> <!-- Relative paths to support mirror sites with non-standard GB docs install --> <!--#include virtual="$ROOT/inc/gbPageStart.html" --> <h1>REST API data interface</h1> <h2>Contents</h2> +<h6><a href="#alternatives">Why you may not want to use this API</a></h6> <h6><a href="#REST">What is REST?</a></h6> <h6><a href="#Intro">What is JSON output 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="#Mirrors">Using the API on mirrors and local installations</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="#Search_examples">Example data access, Search functions</a></h6> <h6><a href="#Error_examples">Error return examples</a></h6> <h6><a href="#Practical_examples">Practical examples</a></h6> +<!-- ========== Do not use this API ============================== --> +<h2 id='alternatives'>Why you may not want to use this API</h2> +<p> +Genomic data is not tiny, and usually computational biologists need all the +data for their analyses. Web APIs as a technology were made for grabbing +rather small pieces of data, often from Javascript. This means that Web APIs +may not be the best way to get our data. For this reason, we also provide all +our data through our +<a href="https://genome.ucsc.edu/cgi-bin/hgTables">Table Browser</a> for custom +exports and reports as tab-separated files and can be +joined with other tables. For tracks that are stored in MySQL, our +MySQL/MariaDB server is +<a href="https://genome.ucsc.edu/goldenPath/help/mysql.html">publicly +accessible</a>. Also, dumps of SQL-stored tracks +as well as tracks in binary file formats can be found on our +<a href="https://hgdownload.soe.ucsc.edu/">download server</a>. All binary +files on the download server (bigBed, bigWig and derivatives like bigPsl, bigChain, etc) can even be +<a href="https://hgdownload.soe.ucsc.edu/downloads.html#gbdb">streamed over +HTTP</a>. All these options are faster for bulk downloads and often easier to +parse from scripting languages. +</p> +<p>If however you write Javascript clients or just need a few features given a +range or you like APIs for other reasons, then the endpoints documented on this +page may solve your problem. If you are missing an option or endpoint below for +your use case, let us know. +</p> + <!-- ========== What is REST? ============================== --> <a id="REST"></a> -<h2>What is REST?</h2> +<h2>What are REST and JSON?</h2> <p> REST is an acronym for REpresentational State Transfer. It states architectural guidelines for how an API will operate. See also: <a target="_blank" href="https://restfulapi.net/">Principles -of REST</a> -</p> - -<!-- ========== What is JSON data? ============================== --> -<a id="Intro"></a> -<h2>What is JSON output data?</h2> -<p> -The REST API returns data in JSON format. JSON data is a data transfer -syntax from a data provider to a data consumer. +of REST</a>. +Like most APIs, ours returns data in JSON format. JSON data is a data transfer +syntax almost identical to the Javascript object and array syntax. 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 the endpoint functions. For example: <pre> wget -O- 'https://api.genome.ucsc.edu/list/publicHubs' </pre> </p>