bf6b2d5aeaf8111cfd9782b265893c6f14072939
lrnassar
Mon Apr 29 13:40:03 2019 -0700
Fixing some word flow/coding conventions on API help page ref#18869
diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html
index b52332a..4b93b8b 100755
--- src/hg/htdocs/goldenPath/help/api.html
+++ src/hg/htdocs/goldenPath/help/api.html
@@ -1,203 +1,261 @@
JSON API data interface
Contents
What is JSON data ?
JSON data is a data transfer syntax from a data provider to a data consumer.
See also: JSON Introduction
What is the access URL ?
This access url: https://api-test.gi.ucsc.edu/ is used to access
the endpoint functions. For example:
wget -O- 'https://api-test.gi.ucsc.edu/list/publicHubs'
What type of data can be accessed ?
The following data sets can be accessed at this time:
-- Listing of available public hubs
-- Listing of available UCSC browser genome assemblies
+- List of available public hubs
+- List of available UCSC Genome Browser genome assemblies
- List genomes from a specified assembly or track hub
-- List available data tracks from a specified hub or UCSC browser genome assembly (see also: List available data tracks from a specified hub or UCSC Genome Browser genome assembly
+(see also: track definition help)
-- List of chromosomes contained in an assembly hub or UCSC browser genome assembly
-
- List of chromosomes contained in a specific track of an assembly or track hub, or UCSC browser
-genome assembly
-
- Return DNA sequence from an assembly hub 2bit file, or UCSC genome browser assembly
-- Return track data from a specified assembly or track hub or UCSC genome browser assembly
+- List of chromosomes contained in an assembly hub or UCSC Genome Browser genome assembly
+
- List of chromosomes contained in a specific track of an assembly or track hub, or UCSC Genome
+Browser genome assembly
+
- Return DNA sequence from an assembly hub 2bit file, or UCSC Genome Browser assembly
+- Return track data from a specified assembly or track hub, or UCSC Genome Browser assembly
Endpoint functions to return data
-Use the url: https://api-test.gi.ucsc.edu/ is access
+The url https://api-test.gi.ucsc.edu/ is used to access
the endpoint functions. For example:
wget -O- 'https://api-test.gi.ucsc.edu/list/publicHubs'
- /list/publicHubs - list public hubs
-- /list/ucscGenomes - list UCSC database genomes
+- /list/ucscGenomes - list UCSC Genome Browser database genomes
- /list/hubGenomes - list genomes from specified hub
-- /list/tracks - list data tracks available in specified hub or database genome (see also: track definition help)
-- /list/chromosomes - list chromosomes from a data track in specified hub or database genome
+- /list/tracks - list data tracks available in specified hub or database genome
+(see also: track definition help)
+- /list/chromosomes - list chromosomes from a data track in specified hub or database
+genome
- /getData/sequence - return sequence from specified hub or database genome
- /getData/track - return data from specified track in hub or database genome
Parameters to endpoint functions
- hubUrl=<url> - specify track hub or assembly hub URL
-- genome=<name> - specify genome assembly in UCSC genome browser, track or assembly hub
-- track=<trackName> - specify data track in hub or UCSC database genome assembly
+- genome=<name> - specify genome assembly in UCSC Genome Browser or track/assembly hub
+- track=<trackName> - specify data track in track/assembly hub or UCSC database genome
+assembly
- chrom=<chrN> - specify chromosome name for sequence or track data
-- start=<123> - specify start coordinate (0 relative) for data from track or sequence retrieval (start and end required together)
-- end=<456> - specify end coordinate (1 relative) for data from track or sequence retrieval (start and end required together)
-- (see also: UCSC browser coordinate counting systems)
-- maxItemsOutput=1000 - limit number of items to output, default: 1,000, maximum limit: 1,000,000 (use -1 to get maximum output)
-- trackLeavesOnly=1 - on /list/tracks function, only show tracks, do not show composite container information
-- jsonOutputArrays=1 - on /getData/track function, JSON format is array type for each item of data, instead of the default object type
+
- start=<123> - specify start coordinate (0 relative) for data from track or sequence
+retrieval (start and end required together). See also: UCSC browser coordinate counting systems
+- end=<456> - specify end coordinate (1 relative) for data from track or sequence
+retrieval (start and end required together). See also: UCSC browser coordinate counting systems
+- maxItemsOutput=1000 - limit number of items to output, default: 1,000, maximum limit:
+1,000,000 (use -1 to get maximum output)
+- trackLeavesOnly=1 - on /list/tracks function, only show tracks, do not show
+composite container information
+- jsonOutputArrays=1 - on /getData/track function, JSON format is array type
+for each item of data, instead of the default object type
The parameters are added to the endpoint URL beginning with a
question mark ?, and multiple parameters are separated with
the semi-colon ;. For example:
https://api-test.gi.ucsc.edu/getData/sequence?genome=ce11;chrom=chrM
Required and optional parameters
| Endpoint function | Required | Optional |
|---|
| /list/publicHubs | (none) | (none) |
|---|
| /list/ucscGenomes | (none) | (none) |
|---|
| /list/hubGenomes | hubUrl | (none) |
|---|
| /list/tracks | genome or (hubUrl and genome) | trackLeavesOnly=1 |
|---|
| /list/chromosomes | genome or (hubUrl and genome) | track |
|---|
-| /getData/sequence | (genome or (hubUrl and genome)) and chrom | start and end |
|---|
-| /getData/track | (genome or (hubUrl and genome)) and track | chrom, (start and end), maxItemsOutput, jsonOutputArrays |
|---|
+| /getData/sequence | (genome or (hubUrl and genome)) and chrom | start and
+end |
|---|
+| /getData/track | (genome or (hubUrl and genome)) and track | chrom,
+(start and end), maxItemsOutput, jsonOutputArrays |
|---|
The hubUrl and genome parameters are required together to
specify a unique genome in an assembly or track hub. The genome for
a track hub will usually be a UCSC database genome. Assembly hubs will
have their own unique genome sequences. Specify genome without
-a hubUrl to refer to a UCSC genome browser assembly.
+a hubUrl to refer to a UCSC Genome Browser assembly.
Using the chrom=<name> parameter will limit the request
to the single specified chromosome. To limit the request to a specific
position, both start=4321 and end=5678 must be given together.
Supported track types, at this time (April 2019), for getData functions
Example data access
Listing functions
-- list public hubs - api.genome.ucsc.edu/list/publicHubs
-- list UCSC database genomes - api.genome.ucsc.edu/list/ucscGenomes
-- list genomes from specified hub - api.genome.ucsc.edu/list/hubGenomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt
-- list tracks from specified hub and genome - api.genome.ucsc.edu/list/tracks?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1
-- list tracks from UCSC database genome - api.genome.ucsc.edu/list/tracks?genome=ce11
-- list chromosomes from UCSC database genome - api.genome.ucsc.edu/list/chromosomes?genome=ce11
-- list chromosomes from specified track in UCSC database genome - api.genome.ucsc.edu/list/chromosomes?genome=ce11;track=gold
-- list chromosomes from assembly hub genome -
api.genome.ucsc.edu/list/chromosomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1
-- list chromosomes from specified track in assembly hub genome -
api.genome.ucsc.edu/list/chromosomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_
+- list public hubs -
+api.genome.ucsc.edu/list/publicHubs
+- list UCSC database genomes -
+api.genome.ucsc.edu/list/ucscGenomes
+- list genomes from specified hub -
+api.genome.ucsc.edu/list/hubGenomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt
+- list tracks from specified hub and genome -
+api.genome.ucsc.edu/list/tracks?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1
+- list tracks from UCSC database genome -
+api.genome.ucsc.edu/list/tracks?genome=ce11
+- list chromosomes from UCSC database genome -
+api.genome.ucsc.edu/list/chromosomes?genome=ce11
+- list chromosomes from specified track in UCSC database genome -
+api.genome.ucsc.edu/list/chromosomes?genome=ce11;track=gold
+- list chromosomes from assembly hub genome -
+
api.genome.ucsc.edu/list/chromosomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1
+- list chromosomes from specified track in assembly hub genome -
+
api.genome.ucsc.edu/list/chromosomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_
getData functions
-- Get DNA sequence from specified chromosome in UCSC database genome -
api.genome.ucsc.edu/getData/sequence?genome=ce11;chrom=chrM
-- Get DNA sequence from specified chromosome and start,end coordinates in UCSC database genome -
api.genome.ucsc.edu/getData/sequence?genome=ce11;chrom=chrM;start=4321;end=5678
-- Get DNA sequence from a track hub where 'genome' is a UCSC database -
api.genome.ucsc.edu/getData/sequence?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;chrom=chrM;start=4321;end=5678
-- Get DNA sequence from specified chromosome and start,end coordinates in an assembly hub genome -
api.genome.ucsc.edu/getData/sequence?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;chrom=chrCp;start=4321;end=5678
-- Get track data for specified track in UCSC database genome -
api.genome.ucsc.edu/getData/track?genome=ce11;track=gold;maxItemsOutput=100
-- Get track data for specified track and chromosome in UCSC database genome -
api.genome.ucsc.edu/getData/track?genome=ce11;track=gold;chrom=chrM
-- Get track data for specified track, chromosome and start,end coordinates in UCSC database genome -
api.genome.ucsc.edu/getData/track?genome=ce11;track=gold;chrom=chrI;start=47000;end=48000
-- Get track data for specified track in an assembly hub genome -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_
-- Get track data for specified track and chromosome in an assembly hub genome -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrCp
-- Get track data for specified track in a track hub -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;track=ultraConserved
-- Get track data for specified track and chromosome in a track hub -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;track=ultraConserved;chrom=chr8
-- Wiggle track data for specified track, chromosome with start and end limits in an assembly hub genome -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrCp;start=4321;end=5678
-- Wiggle track data for specified track in a UCSC database genome -
api.genome.ucsc.edu/getData/track?genome=galGal6;track=gc5BaseBw;maxItemsOutput=100
-- bigBed data from a UCSC database, chrom and start,end limits -
api.genome.ucsc.edu/getData/track?genome=galGal6;track=ncbiRefSeqOther;chrom=chr1;start=750000;end=55700000
+- Get DNA sequence from specified chromosome in UCSC database genome -
+
api.genome.ucsc.edu/getData/sequence?genome=ce11;chrom=chrM
+- Get DNA sequence from specified chromosome and start,end coordinates in UCSC database genome -
+
api.genome.ucsc.edu/getData/sequence?genome=ce11;chrom=chrM;start=4321;end=5678
+- Get DNA sequence from a track hub where 'genome' is a UCSC database -
+
api.genome.ucsc.edu/getData/sequence?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;chrom=chrM;start=4321;end=5678
+- Get DNA sequence from specified chromosome and start,end coordinates in an assembly hub genome -
+
api.genome.ucsc.edu/getData/sequence?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;chrom=chrCp;start=4321;end=5678
+- Get track data for specified track in UCSC database genome -
+
api.genome.ucsc.edu/getData/track?genome=ce11;track=gold;maxItemsOutput=100
+- Get track data for specified track and chromosome in UCSC database genome -
+
api.genome.ucsc.edu/getData/track?genome=ce11;track=gold;chrom=chrM
+- Get track data for specified track, chromosome and start,end coordinates in UCSC database genome -
+
api.genome.ucsc.edu/getData/track?genome=ce11;track=gold;chrom=chrI;start=47000;end=48000
+- Get track data for specified track in an assembly hub genome -
+
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_
+- Get track data for specified track and chromosome in an assembly hub genome -
+
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrCp
+- Get track data for specified track in a track hub -
+
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;track=ultraConserved
+- Get track data for specified track and chromosome in a track hub -
+
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;track=ultraConserved;chrom=chr8
+- Wiggle track data for specified track, chromosome with start and end limits in an assembly hub genome -
+
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrCp;start=4321;end=5678
+- Wiggle track data for specified track in a UCSC database genome -
+
api.genome.ucsc.edu/getData/track?genome=galGal6;track=gc5BaseBw;maxItemsOutput=100
+- bigBed data from a UCSC database, chrom and start,end limits -
+
api.genome.ucsc.edu/getData/track?genome=galGal6;track=ncbiRefSeqOther;chrom=chr1;start=750000;end=55700000
Error return examples
-- Request track data for non-existent chromosome in an assembly hub genome -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrI;start=43521;end=54321
+- Request track data for non-existent chromosome in an assembly hub genome -
+
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrI;start=43521;end=54321