c8ce6b749afee2a94df5a0b06fd79a8f29e33b44 jnavarr5 Fri Jul 5 16:27:26 2024 -0700 Adding a conditions of use to the hubApi documentation page, refs #32003. Making edits to Max's 'why not to use the API' section, refs #34072 diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html index 4cf0417..6cd287b 100755 --- src/hg/htdocs/goldenPath/help/api.html +++ src/hg/htdocs/goldenPath/help/api.html @@ -16,52 +16,78 @@
What type of data can be accessed?
Endpoint functions
Parameters to endpoint functions
Required and optional parameters
Supported track types
Using the API on mirrors and local installations
Example data access, list functions
Example data access, getData functions
Example data access, Search functions
Error return examples
Practical examples

Why you may not want to use this API

-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 -Table Browser 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 -publicly -accessible. Also, dumps of SQL-stored tracks -as well as tracks in binary file formats can be found on our -download server. All binary -files on the download server (bigBed, bigWig and derivatives like bigPsl, bigChain, etc) can even be -streamed over -HTTP. All these options are faster for bulk downloads and often easier to -parse from scripting languages. +Genomic data is considerably large, and computational biologists generally need all the +data that is available for their analyses. Web APIs, as a technology, were designed for retrieving +relatively small pieces of data, often from Javascript. Consequently, Web APIs +may not be the best way to get data from the UCSC Genome Browser.

+

+For this reason, we also provide alternative methods to access our data: +

+

+All these options offer faster bulk downloads and are often easier to parse from scripting +languages. If, however, you write Javascript clients or need only a few features within a given +range, then the endpoints documented on this page may address your needs. If you require an +option or endpoint not listed below for your specific use case, contact us and we can try and implement the feature.

-

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. +

Conditions of use

+ +

+For more details about the Conditions of Use, please refer to the following page, +Genome Browser Conditions of Use. +If you plan to execute a query that you think may be excessive, contact UCSC first to avoid the possibility of temporarily restricting your +access to the REST API.

What are REST and JSON?

REST is an acronym for REpresentational State Transfer. It states architectural guidelines for how an API will operate. See also: Principles of REST. 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: JSON Introduction