A Simplified RESTful workflow

Registration API

In all the following examples, it is assumed the client has successfully logged in as user exampleuser and password examplepassword and therefore obtained a valid access token. This token is used in all the following endpoint examples except /api/login.

GET /api/login

Authenticate the client and obtain an access token in order to make subsequent requests to the Registration API.

If the request is successful, the response is formatted as a JSON object with a single key (auth_token), whose value is the access token. This token must be included as an Authorization: Token header in all subsequent requests.

Resource Information

Parameters

None.

Example Request

    GET https://trackhubregistry.org/api/login
    Authorization: Basic ZXhhbXBsZXVzZXI6ZXhhbXBsZXBhc3N3b3Jk

Example Response

    HTTP/1.0 200 OK
    Content-type: application/json; charset=utf-8
    ...
    {
      "auth_token":"6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi"
    }

HTTP Status Codes

GET /api/trackhub

Returns the set of registered track data hubs for the given user.

If the request is successful, the response body is an array of JSON objects representing track hubs registered by the user. A track hub object has the following attributes:

• name: the single-word track hub name;
• url: the track hub remote URL;
• shortLabel: the short name for the track hub;
• longLabel: the longer descriptive label for the track hub;
• trackdbs: a list of objects for each trackDb (i.e. assembly specific data files) associated to the track hub. Each trackDb object contains the species NCBI tax id and assembly accession, and the URI of the JSON representation of the trackDb which can be retrieved from the Registry.

Resource Information

Parameters

None.

Example Request

    GET https://trackhubregistry.org/api/trackhub
    User: exampleuser
    Authorization: Token 6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi

Example Response

    HTTP/1.0 200 OK
    ...
    [
      {
        'trackdbs': [
                            {
                              'species': '3988',
                              'assembly': 'GCA_000151685.2',
                              'uri': 'https://trackhubregistry.org/api/trackdb/1'
                            },
                            {
                              'species': '3711',
                              'assembly': 'GCA_000309985.1',
                              'uri': 'https://trackhubregistry.org/api/trackdb/2'
                            },
                            {
                              'species': '3702',
                              'assembly': 'GCA_000001735.1',
                              'uri': 'https://trackhubregistry.org/api/trackdb/3'
                            }
                          ],
        'shortLabel': 'Plants',
        'name': 'cshl2013',
        'url': 'http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt',
        'longLabel': 'CSHL Biology of Genomes meeting 2013 demonstration assembly hub'
      },
      {
        'trackdbs': [
                            {
                              'species': '9606',
                              'assembly': 'GCA_000001405.15',
                              'uri': 'https://trackhubregistry.org/api/trackdb/4'
                            },
                            {
                              'species': '9606',
                              'assembly': 'GCA_000001405.1',
                              'uri': 'https://trackhubregistry.org/api/trackdb/5'
                            }
                          ],
        'shortLabel': 'Ensembl Regulatory Build',
        'name': 'EnsemblRegulatoryBuild',
        'url': 'http://ngs.sanger.ac.uk/production/ensembl/regulation/hub.txt',
        'longLabel': 'Evidence summaries and provisional results for the new Ensembl Regulatory Build'
      },
    ]

HTTP Status Codes

POST /api/trackhub

Register a remote public track hub with the Registry. The message body specifies the track hub remote URL (can be either the directory or hub.txt file URL), a map from assembly names as specified in the hub to INSDC accessions (in case of assemblies not supported by UCSC, see genome assembly support), and, optionally, the hub assemblies data type (default: genomics). See Message Format for a list of possible types.

If the track hub at the specified URL has not been previously submitted, the Registry will register it by translating its trackDb files into JSON documents adhering to a particular JSON schema version. If the track hub has already been submitted, an error will be prompted to ask you to use PUT API to update the hub or letting you know that the hub is already submitted by another user.

If the request is successful, the response body is formatted as an array of JSON objects, where each object is a translation of a trackDb document belonging to the track hub. The response contains the header Location which specifies the URIs of the trackDb documents in their same respective order in the response body.

Resource Information

Parameters

• version (optional): JSON schema version of the registered trackDb documents for this hub (default: v1.0, see Modelling Track Hubs for a discussion)

Message

            {
              "type": "object",

              "properties": {
                "url":    { 
                  "description": "The hub URL (i.e. location of the hub.txt file)",
                  "type": "string", 
                  "format": "uri"
                },
                "type":  {
                  "description": "The main type of data contained in the hub",
                  "type": "string", 
                  "enum": [ "genomics", "epigenomics", "transcriptomics", "proteomics" ] 
                },
                "public": {
                  "description": "Whether the hub is available for search (1) or not (0)",
                  "type": "number"
                },
                "assemblies": {
                  "type": "object",
                  "patternProperties": {
                    "[a-zA-z][a-zA-Z0-9]+$": { "type": "string", "pattern": "^G(CA|CF)_[0-9]+.[0-9]+$" }
                  }
                }
              }

              "required": [ "url" ]
            }

            { 
              "url" : "http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt", 
              "assemblies": {
                "araTha1": 'GCA_000001735.1',
                "ricCom1": 'GCA_000151685.2',
                "braRap1": 'GCA_000309985.1'
              }
            }

Example Request

In this example, we are requesting to register/update the CSHL Biology of Genomes meeting 2013 demonstration hub, which contains data for three assemblies referred to by the names "araTha1", "ricCom1" and "braRap1" respectively.

Important Note

As can be seen in the body of the following request, we're posting the mapping between the above hub assembly names and their respective INSDC accessions. This is because this is an assembly hub and there's no other way for the Registry to infer species/assembly information.

    POST https://trackhubregistry.org/api/trackhub
    User: exampleuser
    Authorization: Token 6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi
    {
      "url": "http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt",
      "assemblies": {
        "araTha1": 'GCA_000001735.1',
        "ricCom1": 'GCA_000151685.2',
        "braRap1": 'GCA_000309985.1'
      }
    }

Example Response

When the hub is submitted succesfully

    HTTP/1.0 201 OK
    Content-type: application/json
    Location: [ 
        'https://trackhubregistry.org/api/trackdb/KRBr5PS7RmapaFr7ofpTBA, 
        'https://trackhubregistry.org/api/trackdb/hB8Npdm1ST2gBwkbQThkVg', 
        'https://trackhubregistry.org/api/trackdb/FOEM87nETMOCOglmm0sSsg' 
    ]
    ...
    [
      {
        // trackDb #1 JSON object
      },
      {
        // trackDb #2 JSON object
      },
      {
        // trackDb #3 JSON object
      }
    ]

The response body is an array of the three corresponding trackDb representations, with the header Location reporting their respective URIs in the same order.

When trying to submit hub (using POST) that exist already

    HTTP/1.0 201 OK
    Content-type: application/json
    {
         "error": "This hub is already submitted, please use PUT /api/trackhubs/<hub_id> 
          endpoint to update it, the hub ID is '8281'"
    }

HTTP Status Codes

PUT /api/trackhub/:id

Update a remote public track hub with the Registry. The message body specifies the track hub remote URL (can be either the directory or hub.txt file URL), a map from assembly names as specified in the hub to INSDC accessions (in case of assemblies not supported by UCSC, see genome assembly support), and, optionally, the hub assemblies data type (default: genomics). See Message Format for a list of possible types.

If the track hub has already been submitted by the same user, the request will update the details of the registered track hub (e.g. the remote track hub has been updated and you want to keep its details in the Registry up to date). In this case, the Registry will delete the relevant trackDb documents and replace them with translations of their most up-to-date versions.

If the request is successful, the response body will contain a success message letting the user know that the hub is updated successfully.

Resource Information

Parameters

• version (optional): JSON schema version of the registered trackDb documents for this hub (default: v1.0, see Modelling Track Hubs for a discussion)

Message

            {
              "type": "object",

              "properties": {
                "url":    { 
                  "description": "The hub URL (i.e. location of the hub.txt file)",
                  "type": "string", 
                  "format": "uri"
                },
                "type":  {
                  "description": "The main type of data contained in the hub",
                  "type": "string", 
                  "enum": [ "genomics", "epigenomics", "transcriptomics", "proteomics" ] 
                },
                "public": {
                  "description": "Whether the hub is available for search (1) or not (0)",
                  "type": "number"
                },
                "assemblies": {
                  "type": "object",
                  "patternProperties": {
                    "[a-zA-z][a-zA-Z0-9]+$": { "type": "string", "pattern": "^G(CA|CF)_[0-9]+.[0-9]+$" }
                  }
                }
              }

              "required": [ "url" ]
            }

            { 
              "url" : "http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt", 
              "assemblies": {
                "araTha1": 'GCA_000001735.1',
                "ricCom1": 'GCA_000151685.2',
                "braRap1": 'GCA_000309985.1'
              }
            }

Example Request

In this example, we are requesting to update the CSHL Biology of Genomes meeting 2013 demonstration hub, which contains data for three assemblies referred to by the names "araTha1", "ricCom1" and "braRap1" respectively.

Important Note

As can be seen in the body of the following request, we're posting the mapping between the above hub assembly names and their respective INSDC accessions. This is because this is an assembly hub and there's no other way for the Registry to infer species/assembly information.

    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",
      "assemblies": {
        "araTha1": 'GCA_000001735.1',
        "ricCom1": 'GCA_000151685.2',
        "braRap1": 'GCA_000309985.1'
      }
    }

Example Response

When the hub is updated succesfully

    HTTP/1.0 201 OK
    Content-type: application/json
    {
	"success": "The hub is submitted/updated successfully"
    }

When trying to update a hub which is already submitted by a different user

    HTTP/1.0 403 Forbidden
    Content-type: application/json
    {
         "error": "The hub you're trying to update is submitted by a different user!"
    }

When trying to update a hub that doesn't exist

    HTTP/1.0 401 Unauthorized
    Content-type: application/json
    {
         "error": "Hub doesn't exist"
    }

HTTP Status Codes

GET /api/trackhub/:id

Return a JSON representation of a track hub with the given name in the Registry.

Resource Information

Parameters

Example Request

    GET https://trackhubregistry.org/api/trackhub/cshl2013
    User: exampleuser
    Authorization: Token 6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi

Example Response

    HTTP/1.0 200 OK
    Content-type: application/json
    ...
    {
    }

HTTP Status Codes

DELETE /api/trackhub/:id

Delete trackDBs assigned to a given track hub.

Resource Information

Parameters

Example Request

    DELETE https://trackhubregistry.org/api/trackhub/cshl2013
    User: exampleuser
    Authorization: Token 6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi

Example Response

    HTTP/1.0 200 OK
    Content-type: application/json
    { 'message': 'Deleted trackDBs from track hub cshl2013' }

HTTP Status Codes

GET /api/trackdb/:id

Return JSON representation of a trackDb with the given ID in the Registry.

Resource Information

Parameters

Example Request

    GET https://trackhubregistry.org/api/trackdb/knB1GHPYSdmeypb-R8sxhA
    User: exampleuser
    Authorization: Token 6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi

Example Response

    HTTP/1.0 200 OK
    Content-type: application/json
    ...
    {
          'owner': 'exampleuser',
          'created': 1440778576,
          'version': 'v1.0',
          'type': 'genomics',
          'source': {
                        'checksum': 'f9561ae6f7883add3698fad7abab7e13',
                        'url': 'http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/ricCom1/trackDb.txt'
                      },
          'hub': {
                     'shortLabel': 'Plants',
                     'name': 'cshl2013',
                     'url': 'http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt',
                     'longLabel': 'CSHL Biology of Genomes meeting 2013 demonstration assembly hub'
                   },
          'species': {
                         'scientific_name': 'Ricinus communis',
                         'common_name': 'castor bean',
                         'tax_id': '3988'
                       },
          'assembly': {
                          'synonyms': 'ricCom1',
                          'name': 'JCVI_RCG_1.1',
                          'accession': 'GCA_000151685.2'
                        },

          'configuration': {
                               'repeatMasker_': {
                                                    'priority': '149.1',
                                                    'visibility': 'dense',
                                                    'compositeTrack': 'on',
          ...
    }

HTTP Status Codes

DELETE /api/trackdb/:id

Delete the trackDb with the given ID from the Registry.

If the request is successful, the response body is a JSON object representing the deleted trackDb.

Notes

Alternatively, this operation can be done more simply using the web interface.

Resource Information

Parameters

Example Request

    DELETE https://trackhubregistry.org/api/trackdb/knB1GHPYSdmeypb-R8sxhA
    User: exampleuser
    Authorization: Token 6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi

Example Response

    HTTP/1.0 200 OK
    ...
    {
          'owner': 'exampleuser',
          'created': 1440778576,
          'version': 'v1.0',
          'type': 'epigenomics',
          ...
          ...
    }   

HTTP Status Codes

GET /api/logout

Logout and invalidate the current access token.

If the request is successful, the response body is a JSON object with message "Successfully logged out".

Resource Information

Parameters

None.

Example Request

    GET https://trackhubregistry.org/api/logout
    User: exampleuser
    Authorization: Token 6l5/GuIiOSCywuSI9HF1VU97clwb/CXPDFS0MyAB/HCZuxtjQBj4uORZL8NY3Yhi

Example Response

    HTTP/1.0 200 OK
    ...
    { "message": "Successfully logged out" }

HTTP Status Codes