185686eee12878de494bd96ab0e3e8be4c8d03ed hiram Fri Mar 15 17:16:37 2019 -0700 adding user documentation refs #18869 diff --git src/hg/hubApi/hubApi.c src/hg/hubApi/hubApi.c index 4cbfffb..09e9dac 100644 --- src/hg/hubApi/hubApi.c +++ src/hg/hubApi/hubApi.c @@ -4,31 +4,31 @@ /* +------------------+------------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +------------------+------------------+------+-----+---------+-------+ | hubUrl | longblob | NO | PRI | NULL | | | shortLabel | varchar(255) | NO | | NULL | | | longLabel | varchar(255) | NO | | NULL | | | registrationTime | varchar(255) | NO | | NULL | | | dbCount | int(10) unsigned | NO | | NULL | | | dbList | blob | YES | | NULL | | | descriptionUrl | longblob | YES | | NULL | | +------------------+------------------+------+-----+---------+-------+ */ /* Global Variables */ -static boolean debug = TRUE; +static boolean debug = FALSE; static struct cart *cart; /* CGI and other variables */ static struct hash *oldVars = NULL; static struct hash *trackCounter = NULL; static long totalTracks = 0; static boolean measureTiming = FALSE; /* set by CGI parameters */ static boolean allTrackSettings = FALSE; /* checkbox setting */ static char **shortLabels = NULL; /* public hub short labels in array */ // struct hubPublic *publicHubList = NULL; static int publicHubCount = 0; static char *defaultHub = "Plants"; static char *defaultDb = "ce11"; static long enteredMainTime = 0; /* will become = clock1000() on entry */ /* to allow calculation of when to bail out, taking too long */ static long timeOutSeconds = 100; static boolean timedOut = FALSE; @@ -597,68 +597,113 @@ if (countTracks->elCount) { hPrintf("
    \n"); struct hashEl *hel, *helList = hashElListHash(countTracks); slSort(&helList, hashElCmpIntValDesc); for (hel = helList; hel; hel = hel->next) { hPrintf("
  1. %d - %s
    2. \n", ptToInt(hel->val), hel->name); } hPrintf("
\n"); } hPrintf("\n"); hPrintf("

\n"); } // static void tracksForUcscDb(char * db) +static void introductionText() +/* output explanation text */ +{ +char *scriptUri = getenv("SCRIPT_URI"); + +hPrintf("

JSON data API interface to U.C. Santa Cruz genome browser data

\n"); +hPrintf("

Data access URL: %s

\n", scriptUri); +hPrintf("

Endpoint functions:

\n"); +hPrintf("\n"); +hPrintf("

Parameters to endpoint functions:

\n"); +hPrintf("\n"); +} + static void showExamples(char *url, struct trackHubGenome *hubGenome, char *ucscDb) { +char *urlPrefix = ""; +char *httpHost = getenv("HTTP_HOST"); + +if (! startsWith("hgwdev-api", httpHost)) { + if (startsWith("hgwdev",httpHost) || startsWith("genome-test", httpHost)) + { + urlPrefix = "../cgi-bin/hubApi"; + } +} hPrintf("

Example URLs to return json data structures:

\n"); hPrintf("

listing functions

\n"); hPrintf("
    \n"); -hPrintf("
  1. list public hubs /list/publicHubs
    2. \n"); -hPrintf("
  2. list database genomes /list/ucscGenomes
    3. \n"); -hPrintf("
  3. list genomes from specified hub /list/hubGenomes?hubUrl=%s
    4. \n", url, url); -hPrintf("
  4. list tracks from specified hub and genome /list/tracks?hubUrl=%s&genome=%s
    5. \n", url, url, hubGenome->name, url, hubGenome->name); -hPrintf("
  5. list tracks from specified UCSC database /list/tracks?db=%s
    6. \n", ucscDb, ucscDb); -hPrintf("
  6. list chromosomes from specified UCSC database /list/chromosomes?db=%s
    7. \n", ucscDb, ucscDb); -hPrintf("
  7. list chromosomes from specified track from UCSC databaset /list/chromosomes?db=%s&track=gap
    8. \n", ucscDb, ucscDb); +hPrintf("
  8. list public hubs %s/list/publicHubs
    9. \n", urlPrefix, urlPrefix); +hPrintf("
  9. list database genomes %s/list/ucscGenomes
    10. \n", urlPrefix, urlPrefix); +hPrintf("
  10. list genomes from specified hub %s/list/hubGenomes?hubUrl=%s
    11. \n", urlPrefix, url, urlPrefix, url); +hPrintf("
  11. list tracks from specified hub and genome %s/list/tracks?hubUrl=%s&genome=%s
    12. \n", urlPrefix, url, hubGenome->name, urlPrefix, url, hubGenome->name); +hPrintf("
  12. list tracks from specified UCSC database %s/list/tracks?db=%s
    13. \n", urlPrefix, ucscDb, urlPrefix, ucscDb); +hPrintf("
  13. list chromosomes from specified UCSC database %s/list/chromosomes?db=%s
    14. \n", urlPrefix, ucscDb, urlPrefix, ucscDb); +hPrintf("
  14. list chromosomes from specified track from UCSC databaset %s/list/chromosomes?db=%s&track=gap
    15. \n", urlPrefix, ucscDb, urlPrefix, ucscDb); hPrintf("
\n"); hPrintf("

getData functions

\n"); hPrintf("
    \n"); -hPrintf("
  1. get sequence from specified database and chromosome /getData/sequence?db=%s&chrom=chrM
    2. \n", ucscDb, ucscDb); -hPrintf("
  2. get sequence from specified database, chromosome with start,end coordinates /getData/sequence?db=%s&chrom=chrM&start=0&end=128
    3. \n", ucscDb, ucscDb); -hPrintf("
  3. get entire track data from specified database and track name (gold == Assembly) /getData/track?db=%s&track=gold
    4. \n", ucscDb, ucscDb); -hPrintf("
  4. get track data from specified database, chromosome and track name (gold == Assembly) /getData/track?db=%s&chrom=chrM&track=gold
    5. \n", ucscDb, ucscDb); -hPrintf("
  5. get track data from specified database, chromosome, track name, start and end coordinates /getData/track?db=%s&chrom=chrI&track=gold&start=107680&end=186148
    6. \n", defaultDb, defaultDb); -hPrintf("
  6. get entire track data from specified hub and track name /getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt&genome=hg19&track=ultraConserved
    7. \n"); -hPrintf("
  7. get track data from specified hub, chromosome and track name (full chromosome) /getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&chrom=chrCp&track=assembly_
    8. \n"); -hPrintf("
  8. get track data from specified hub, chromosome, track name, start and end coordinates /getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&chrom=chr1&track=assembly_&start=0&end=14309681
    9. \n"); -hPrintf("
  9. get all track data from specified hub and track name /getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&track=gc5Base
    10. \n"); -hPrintf("
  10. get track data from specified hub, chromosome, track name, start and end coordinates /getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&chrom=chrMt&track=gc5Base&start=143600&end=143685
    11. \n"); -hPrintf("
  11. get bigWig track data from specified database, chromosome, track name, start and end coordinates /getData/track?db=%s&chrom=chrI&track=gc5BaseBw&start=107680&end=186148
    12. \n", defaultDb, defaultDb); -hPrintf("
  12. get bigBed track data from specified database, chromosome, track name, start and end coordinates /getData/track?db=%s&chrom=chrII&track=ncbiRefSeqOther&start=14334626&end=14979625
    13. \n", defaultDb, defaultDb); -hPrintf("
  13. get narrowPeak track data from specified database, chromosome, track name, start and end coordinates /getData/track?db=%s&chrom=chr1&track=wgEncodeAwgDnaseDuke8988tUniPk&start=14334626&end=14979625
    14. \n", "hg19", "hg19"); -hPrintf("
  14. get broadPeak track data from specified database, chromosome, track name, start and end coordinates /getData/track?db=%s&chrom=chr1&track=wgEncodeBroadHistoneOsteoP300kat3bPk&start=14334626&end=14979625
    15. \n", "hg19", "hg19"); +hPrintf("
  15. get sequence from specified database and chromosome %s/getData/sequence?db=%s&chrom=chrM
    16. \n", urlPrefix, ucscDb, urlPrefix, ucscDb); +hPrintf("
  16. get sequence from specified database, chromosome with start,end coordinates %s/getData/sequence?db=%s&chrom=chrM&start=0&end=128
    17. \n", urlPrefix, ucscDb, urlPrefix, ucscDb); +hPrintf("
  17. get entire track data from specified database and track name (gold == Assembly) %s/getData/track?db=%s&track=gold
    18. \n", urlPrefix, ucscDb, urlPrefix, ucscDb); +hPrintf("
  18. get track data from specified database, chromosome and track name (gold == Assembly) %s/getData/track?db=%s&chrom=chrM&track=gold
    19. \n", urlPrefix, ucscDb, urlPrefix, ucscDb); +hPrintf("
  19. get track data from specified database, chromosome, track name, start and end coordinates %s/getData/track?db=%s&chrom=chrI&track=gold&start=107680&end=186148
    20. \n", urlPrefix, defaultDb, urlPrefix, defaultDb); +hPrintf("
  20. get entire track data from specified hub and track name %s/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt&genome=hg19&track=ultraConserved
    21. \n", urlPrefix, urlPrefix); +hPrintf("
  21. get track data from specified hub, chromosome and track name (full chromosome) %s/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&chrom=chrCp&track=assembly_
    22. \n", urlPrefix, urlPrefix); +hPrintf("
  22. get track data from specified hub, chromosome, track name, start and end coordinates %s/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&chrom=chr1&track=assembly_&start=0&end=14309681
    23. \n", urlPrefix, urlPrefix); +hPrintf("
  23. get all track data from specified hub and track name %s/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&track=gc5Base
    24. \n", urlPrefix, urlPrefix); +hPrintf("
  24. get track data from specified hub, chromosome, track name, start and end coordinates %s/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&chrom=chrMt&track=gc5Base&start=143600&end=143685
    25. \n", urlPrefix, urlPrefix); +hPrintf("
  25. get bigWig track data from specified database, chromosome, track name, start and end coordinates %s/getData/track?db=%s&chrom=chrI&track=gc5BaseBw&start=107680&end=186148
    26. \n", urlPrefix, defaultDb, urlPrefix, defaultDb); +hPrintf("
  26. get bigBed track data from specified database, chromosome, track name, start and end coordinates %s/getData/track?db=%s&chrom=chrII&track=ncbiRefSeqOther&start=14334626&end=14979625
    27. \n", urlPrefix, defaultDb, urlPrefix, defaultDb); +hPrintf("
  27. get narrowPeak track data from specified database, chromosome, track name, start and end coordinates %s/getData/track?db=%s&chrom=chr1&track=wgEncodeAwgDnaseDuke8988tUniPk&start=14334626&end=14979625
    28. \n", urlPrefix, "hg19", urlPrefix, "hg19"); +hPrintf("
  28. get broadPeak track data from specified database, chromosome, track name, start and end coordinates %s/getData/track?db=%s&chrom=chr1&track=wgEncodeBroadHistoneOsteoP300kat3bPk&start=14334626&end=14979625
    29. \n", urlPrefix, "hg19", urlPrefix, "hg19"); hPrintf("
\n"); hPrintf("

Example URLs to generate errors:

\n"); hPrintf("
    \n"); -hPrintf("
  1. get track data from specified hub, chromosome, track name, start and end coordinates /getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&chrom=chrI&track=assembly_&start=0&end=14309681
    2. \n"); +hPrintf("
  2. get track data from specified hub, chromosome, track name, start and end coordinates %s/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt&genome=_araTha1&chrom=chrI&track=assembly_&start=0&end=14309681
    3. \n", urlPrefix, urlPrefix); hPrintf("
\n"); } /* static void showExamples() */ static void showCartDump() /* for information purposes only during development, will become obsolete */ { hPrintf("

cart dump

"); hPrintf("
\n");
 cartDump(cart);
 hPrintf("
\n"); } static void doMiddle(struct cart *theCart) /* Set up globals and make web page */ { @@ -741,42 +786,47 @@ char *ucscDb = cartUsualString(cart, "ucscGenomes", defaultDb); char *urlInput = urlDropDown; /* assume public hub */ if (sameWord("go", goOtherHub)) /* requested other hub URL */ urlInput = otherHubUrl; if (commandError) { hPrintf("

ERROR: no such command: '%s/%s' for endpoint '%s'

", words[0], words[1], pathInfo); } long lastTime = clock1000(); struct trackHub *hub = errCatchTrackHubOpen(urlInput); if (measureTiming) { long thisTime = clock1000(); + if (debug) hPrintf("hub open time: %ld millis
\n", thisTime - lastTime); } // hPrintf("

ucscDb: '%s'

\n", ucscDb); struct trackHubGenome *hubGenome = hub->genomeList; +introductionText(); + showExamples(urlInput, hubGenome, ucscDb); if (debug) showCartDump(); +hPrintf("

Explore hub or database assemblies and tracks

\n"); + hPrintf("
\n\n", "../cgi-bin/hubApi"); hPrintf("Select public hub: "); #define JBUFSIZE 2048 #define SMALLBUF 256 char javascript[JBUFSIZE]; struct slPair *events = NULL; safef(javascript, sizeof(javascript), "this.lastIndex=this.selectedIndex;"); slPairAdd(&events, "focus", cloneString(javascript)); cgiMakeDropListClassWithIdStyleAndJavascript("publicHubs", "publicHubs", shortLabels, publicHubCount, hubDropDown, NULL, "width: 400px", events); hWrites(" "); hButton("goPublicHub", "go"); @@ -800,42 +850,44 @@ hCheckBox("depthSearch", cartUsualBoolean(cart, "depthSearch", FALSE)); hPrintf(" perform full bbi file measurement : %s (will time out if taking longer than %ld seconds)
\n", depthSearch ? "TRUE" : "FALSE", timeOutSeconds); hPrintf("\n  "); allTrackSettings = cartUsualBoolean(cart, "allTrackSettings", FALSE); hCheckBox("allTrackSettings", allTrackSettings); hPrintf(" display all track settings for each track : %s
\n", allTrackSettings ? "TRUE" : "FALSE"); hPrintf("
\n
\n"); if (sameWord("go", goUcscDb)) /* requested UCSC db track list */ { tracksForUcscDb(ucscDb); } else { + if (debug) + { hPrintf("

URL: %s - %s
\n", urlInput, sameWord("go",goPublicHub) ? "public hub" : "other hub"); hPrintf("name: %s
\n", hub->shortLabel); hPrintf("description: %s
\n", hub->longLabel); hPrintf("default db: '%s'
\n", isEmpty(hub->defaultDb) ? "(none available)" : hub->defaultDb); printf("docRoot:'%s'
\n", docRoot); + } if (hub->genomeList) (void) genomeList(hub, NULL, NULL); /* ignore returned list */ hPrintf("

\n"); } - if (timedOut) hPrintf("

Reached time out %ld seconds

", timeOutSeconds); if (measureTiming) hPrintf("Overall total time: %ld millis
\n", clock1000() - enteredMainTime); cartWebEnd(); } /* void doMiddle(struct cart *theCart) */ /* Null terminated list of CGI Variables we don't want to save * permanently. */ static char *excludeVars[] = {"Submit", "submit", NULL,}; int main(int argc, char *argv[]) /* Process command line. */ {