A Simplified RESTful workflow

Deleting Registered Track Hubs

Suppose one of your registered remote public hubs does not exist or it's not public any more, or you simply don't want to make it available for search in the Track Hub Registry. You can delete a track hub from the Registry (i.e. remove all its associated trackDBs) by making a request to the DELETE /api/trackhub/:id where you specify the name of track hub (i.e. the hub attribute value in the hub.txt file).

Prerequisites

Verify that:

• your client has successfully logged in and have, as such, obtained a valid authentication token;
• the Registry contains trackDBs which are registered as belonging to the hub with the given name

Procedure

1. Make a request to the DELETE /api/trackhub/:id endpoint that includes a User header with your username, and an Authorization: Token header with the given authentication token; the :id parameter must be replaced with the name of the hub as it is known by the Registry;
2. Examine the response. The response code indicates whether the request succeeded, or how it failed;

Example: track hub deletion request and response

In this example, we follow the pattern of the previous steps where we have registered and updated the CSHL Biology of Genomes meeting 2013 demonstration assembly hub. We now want to delete its records in the Registry, corresponding to three trackDbs associated to the an equivalent number of plant assemblies where 1 is the track hub ID.

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

      HTTP/1.0 200 OK
      {
          "success": "Hub 'cshl2013' is deleted successfully"
      }

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 cannot find any trackDB associated to a hub with the supplied name, it returns HTTP response code 404, with the message "Could not find ..."
• 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 = DELETE("$server/api/trackhub/cshl2013");
$request->headers->header(user       => $user);
$request->headers->header(auth_token => $auth_token);
my $response = $ua->request($request);
if ($response->is_success) {
  print "I have deleted the trackDBs associated to the cshl2013 hub\n";
} else {
  die sprintf "Couldn't delete trackDBs: %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;
  } 
}