A Simplified RESTful workflow

Retrieve the list of registered track hubs

Suppose you've already submitted some of your public track hubs. At some point, you want to know which ones by retrieving the list of registered track hubs from the Registry, perhaps because you want to update or delete some of them.

After logging in, your client can simply get the list of registered track hubs by making a request to the GET /api/trackhub endpoint. The response provides overview information on your registered track hubs together with the URIs of their corresponding trackDb entities stored in the Registry.

Prerequisites

Verify that:

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

Procedure

1. Make a GET request to the /api/trackhub 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 array of JSON objects representing track hubs whose trackDbs are registered by the user.

Example: retrieve request and response

We start from the previous example, where user exampleuser submitted one track hub. The client now wants to programatically retrieve a compact representation of the set of its registered track hubs.

As already explained, any request to the Registration API must supply the user's credentials with the following headers:

      User: [username]
      Authorization: Token [valid token]

The GET /api/trackhub endpoint does not accept parameters, so the request in this case is very simple:

Request:

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

If the request is successful, the response body is an array of JSON objects, one for each track hub submitted by the user:

Response:

      200 OK
      Content-type: application/json; charset=utf-8
      ...
      [
        {
          'name': 'cshl2013',
          'shortLabel': 'Plants',
          'longLabel': 'CSHL Biology of Genomes meeting 2013 demonstration assembly hub',
          'url': 'http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt',
          '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'
                            }
                        ]
        }
      ]

As can be seen from the response output, the track hub object contains an array, trackdbs, which is a list of objects containing information for each trackDb (i.e. assembly specific data files) associated with the track hub: the species NCBI tax id and assembly accession, and the URI of the JSON representation of the stored trackDb entity which can be retrieved from the Registry by making a GET request to the /api/trackdb/:id endpoint.

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

use strict;
use warnings;

use JSON;
use HTTP::Request::Common;
use LWP::UserAgent;

my $ua = LWP::UserAgent->new(ssl_opts => { verify_hostname => 0 });
my $server = 'https://trackhubregistry.org';
my ($user, $pass, $auth_token) = ('exampleuser', 'examplepass');

$auth_token = login($server, $user, $pass);

my $request = GET("$server/api/trackhub");
$request->headers->header(user       => $user);
$request->headers->header(auth_token => $auth_token);
my $response = $ua->request($request);
if ($response->is_success) {
  use Data::Dumper;
  local $Data::Dumper::Terse = 1;
  local $Data::Dumper::Indent = 1;
  print "Registered track hubs\n", Dumper from_json($response->content);
} else {
  die sprintf "Couldn't get list of registered trackhubs: %s [%d]", $response->content, $response->code;
} 

logout($server, $user, $auth_token);

sub login {
  my ($server, $user, $pass) = @_;

  my $request = GET("$server/api/login");
  $request->headers->authorization_basic($user, $pass);
  
  my $response = $ua->request($request);
  my $auth_token;
  if ($response->is_success) {
    $auth_token = from_json($response->content)->{auth_token};
    print "Logged in [$auth_token]\n" if $auth_token;
  } else {
    die sprintf "Couldn't login: %s [%d]", $response->content, $response->code;
  }

  return $auth_token;
}

sub logout {
  my ($server, $user, $auth_token) = @_;

  my $request = GET("$server/api/logout");
  $request->headers->header(user       => $user);
  $request->headers->header(auth_token => $auth_token);

  my $response = $ua->request($request);
  if ($response->is_success) {
    print "Logged out\n";
  } else {
    die sprintf "Unable to logout: %s [%d]", $response->content, $response->code;
  } 
}