A Simplified RESTful workflow

Updating Track Hubs

Suppose you've updated the structure or content of one of your remote public hubs registered with us. You obviously want the changes to appear on the Registry as well.

The procedure is similar to Registering Track Hubs: simply PUT the hub URL at /api/trackhub/:id. In case the track hub has already been submitted, the request will update the details of the registered track hub. The Registry will delete the existing stored trackDb entities and replace them with the most up-to-date versions obtained by parsing the hub again.

Prerequisites

Verify that:

• Your client has successfully logged in and have, as such, obtained a valid authentication token.

Procedure

1. Make a PUT request to the /api/trackhub/:id endpoint that includes a User header with your username and an Authorization: Token header with the given authentication token;
2. Examine the response. The response code indicates whether the request succeeded, or how it failed;
3. A successful request returns an success message stating that the hub was updated successfuly.

Example: track hub update

This example updates the registration of the CSHL Biology of Genomes meeting 2013 demonstration assembly hub. This time we don't specify a data type, hence it will default to "genomics":

Request:

      PUT https://trackhubregistry.org/api/trackhub/1
      User: exampleuser
      Authorization: Token 6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi
      {
        "url": "http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt"
      }

What can possibly go wrong

Remember: always check the response code since it indicates whether the request succeeded, or how it failed.

• if the request is successful, the server returns HTTP response code 200 (OK)
• if the credentials supplied in the authentication header are invalid, the server returns HTTP response code 401
• if your hub is not compliant with the UCSC hub specs, the server returns HTTP response code 400. The body contains the message: "hubCheck report: ..."
• if the hub is not available or cannot be correctly parsed, the server returns HTTP response code 400. The response body message contains the error
• your hub genome subdirectory names must be valid UCSC DB names (assembly synonyms, e.g. hg38) or you must provide a map from these names to their corresponding INSDC accessions (i.e. assembly accession + version, e.g. GCA_000001405.1). If neither of the two conditions are met, the server returns HTTP response code 400 with the message "Unable to find a valid INSDC accession for genome assembly [..]"
• if one of the hub trackDb configurations cannot be translated to valid JSON, the server returns HTTP response code 400. The body contains the message "Failed: ..." with an output describing the reasons why validation failed
• if the Registry encountered an unexpected condition which prevented it from fulfilling the request, it returns HTTP response code 500
• if the Registry is currently unable to handle the request due to a temporary overloading or maintenance, it returns HTTP response code 503

Example clients

As already explained, the procedure is equivalent to the registration of a track hub for the first time. You can refer to the workflow section Registering Track Hubs for examples clients in different programming languages.