Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
249 changes: 139 additions & 110 deletions bin/api2html.pl
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@

use Getopt::Long;

use Data::Dumper;

use JSON;
use LWP::UserAgent;

Expand All @@ -23,18 +25,18 @@ sub usage {

GetOptions ( 'url=s' => \$url,
'site_name=s' => \$site_name,
'outfile=s' => \$outfile,
'help!' => \$help );
'outfile=s' => \$outfile,
'help!' => \$help );

if ($help) {
&usage();
exit 0;
&usage();
exit 0;
}

unless ($url and $outfile) {
print "missing required paramater\n";
&usage();
exit 1;
print "missing required paramater\n";
&usage();
exit 1;
}

# initialize json object and user agent
Expand Down Expand Up @@ -71,7 +73,7 @@ sub usage {
my $html = template_start($site_name);

# build the navigation
$html .= '<li><a href="#overview">overview</a></li>';
$html .= '';
foreach my $res (sort { $a->{name} cmp $b->{name} } @{$structure->{resources}}) {
$html .= '<li><a href="#'.$res->{name}.'">'.$res->{name}.'</a></li>';
}
Expand All @@ -80,115 +82,141 @@ sub usage {
<div class="span12" style="margin-left: 270px;">
~;

$html .= "<h1><a name='overview' style='padding-top: 50px;'>".$site_name." Overview</a></h1><p>".$structure->{service}->{description}."</p><hr>";
$structure->{service}->{description} =~ s/\n\n/\<\/p\>\<p\>/g;
$structure->{service}->{description} =~ s/\n/\<br>/g;

$html .= "<h1><a name='overview' style='padding-top: 50px;'>$site_name API Overview</a></h1><p>".$structure->{service}->{description}."</p><hr>";

my %param_types = ( body => "<p>This parameter must be passed in the message body.</p>",
options => "<p>This is an optional parameter and may be passed in the query string.</p>",
required => "<p>This is a required parameter and must be passed as a REST parameter.</p>" );

# iterate over the resources
foreach my $res (sort { $a->{name} cmp $b->{name} } @{$structure->{resources}}) {
print $res->{name}."\n";
$html .= "<h1><a name='".$res->{name}."' style='padding-top: 50px;'>".$res->{name}."</a></h1><h2>Description</h2><p>".$res->{description}."</p>";
foreach my $req (@{$res->{requests}}) {
print "\t".$req->{name}."\n";
$html .= "<h2>".$req->{name}." - request</h2><h3>Description</h3><p>".$req->{description}."</p><p>This is a ".$req->{type}." ".$req->{method}." request.";
unless (ref($req->{attributes})) {
$html .= " This request has no parameters.";
next;
}
$html .= "</p><h3>Parameters</h3><ul>";
# iterate over paramaters
foreach my $ptype (sort keys %param_types) {
foreach my $param (sort keys(%{$req->{parameters}->{$ptype}})) {
my $pm = $req->{parameters}->{$ptype}->{$param};
$pm->[0] =~ s/cv/controlled vocabulary/;
$html .= "<li><b>$param</b> (".$pm->[0];
if (ref($pm->[1]) eq 'ARRAY') {
if (! ref($pm->[0]) && $pm->[0] eq 'list') {
$html .= " of ".$pm->[1]->[0].")</li><p>";
$html .= $pm->[1]->[1]."</p>";
} else {
$html .= ")</li><p>";
$html .= "This parameter value can be chosen from the following (the first being default):</p><ul style='list-style: none;'>";
foreach my $cvitem (@{$pm->[1]}) {
if (ref($cvitem)) {
$html .= "<li><b>".$cvitem->[0]."</b> - ".$cvitem->[1]."</li>";
} else {
$html .= "<li><b>".$cvitem."</b></li>";
}
}
$html .= "</ul><br>";
}
} else {
$html .= ")</p><p>".$pm->[1]."</p>";
}
$html .= $param_types{$ptype};
}
}
$html .= "</ul>";
if (exists $req->{example}) {
$html .= "<h3>Example</h3><ul>";
$html .= "<li>".$req->{example}[0]."<li>".$req->{example}[1]."</ul>";
}
$html .= "<h3>Return Attributes</h3><ul>";
# iterate over attributes
foreach my $param (sort keys(%{$req->{attributes}})) {
my ($att_obj, $att_hash);
my $att = $param;
my $att_type = $req->{attributes}->{$param}->[0];
my $att_desc = $req->{attributes}->{$param}->[1];
if ($att_type eq 'cv') {
$html .= "<li><b>$att</b> (controlled vocabulary)</li><p>";
$html .= "This parameter value can be chosen from the following (the first being default):</p><ul style='list-style: none;'>";
foreach my $cvitem (@$att_desc) {
$html .= "<li><b>".$cvitem->[0]."</b> - ".$cvitem->[1]."</li>";
}
$html .= "</ul><br>";
} else {
while (ref($att_desc) eq 'ARRAY') {
if ($att_type =~ /object/) {
$att_obj = $att_desc->[0];
} elsif (($att_type =~ /hash/) && ref($att_desc) eq 'ARRAY') {
$att_hash = $att_desc->[0];
} else {
$att_type .= " of ".$att_desc->[0]."s";
}
$att_desc = $att_desc->[1];
}
$html .= "<li><b>$att</b> ($att_type)</li><p>";
if ($att_obj) {
$html .= "This attribute has an object structure:</p><ul style='list-style: none;'>";
foreach my $key (sort keys(%$att_obj)) {
my $obj_type = $att_obj->{$key}->[0];
my $obj_att = $att_obj->{$key}->[1];
while (ref($obj_att) eq 'ARRAY') {
$obj_type .= " of ".$obj_att->[0]."s";
$obj_att = $obj_att->[1];
}
$html .= "<li><b>$key ($obj_type)</b> - ".$obj_att."</li>";
}
$html .= "</ul><br>";
} elsif ($att_hash) {
$html .= "This attribute has a hash structure:</p><ul style='list-style: none;'>";
foreach my $key (('key', 'value')) {
my $hash_type = $att_hash->{$key}->[0];
my $hash_att = $att_hash->{$key}->[1];
while (ref($hash_att) eq 'ARRAY') {
$hash_type .= " of ".$hash_att->[0]."s";
$hash_att = $hash_att->[1];
}
$html .= "<li><b>$key ($hash_type)</b> - ".$hash_att."</li>";
}
$html .= "</ul><br>";
} else {
$html .= $att_desc."</p>"
}
}
}
$html .= "</p></ul>";
print $res->{name}."\n";
$html .= "<h1><a name='".$res->{name}."' style='padding-top: 50px;'>".$res->{name}."</a></h1><h2>Description</h2><p>".$res->{description}."</p>";
foreach my $req (@{$res->{requests}}) {
print "\t".$req->{name}."\n";
$html .= "<h2>".$req->{name}." - request</h2><h3>Description</h3><p>".$req->{description}."</p><p>This is a ".$req->{type}." ".$req->{method}." request.";
unless (ref($req->{attributes})) {
$html .= " This request has no parameters.";
next;
}
$html .= "</p><h3>Parameters</h3><ul>";
# iterate over paramaters
foreach my $ptype (sort keys %param_types) {
foreach my $param (sort keys(%{$req->{parameters}->{$ptype}})) {
my $pm = $req->{parameters}->{$ptype}->{$param};
$pm->[0] =~ s/cv/controlled vocabulary/;
$html .= "<li><b>$param</b> (".$pm->[0];
if (ref($pm->[1]) eq 'ARRAY') {
if (! ref($pm->[0]) && $pm->[0] eq 'list') {
while (ref($pm->[1]->[1]) eq 'ARRAY') {
$html .= " of list";
$pm->[1] = $pm->[1]->[1];
}
$html .= " of ".$pm->[1]->[0].")</li><p>";
$html .= $pm->[1]->[1]."</p>";
} else {
$html .= ")</li><p>";
$html .= "This parameter value can be chosen from the following (the first being default):</p><ul style='list-style: none;'>";
foreach my $cvitem (@{$pm->[1]}) {
if (ref($cvitem)) {
$html .= "<li><b>".$cvitem->[0]."</b> - ".$cvitem->[1]."</li>";
} else {
$html .= "<li><b>".$cvitem."</b></li>";
}
}
$html .= "</ul><br>";
}
} else {
$html .= ")</p><p>".$pm->[1]."</p>";
}
$html .= $param_types{$ptype};
}
}
$html .= "</ul>";
if (exists $req->{example}) {
$html .= "<h3>Example</h3><ul>";
$html .= "<li>".$req->{example}[0]."<li>".$req->{example}[1]."</ul>";
}
$html .= "<h3>Return Attributes</h3><ul>";
# iterate over attributes
foreach my $param (sort keys(%{$req->{attributes}})) {
my ($att_obj, $att_hash);
my $att = $param;
my $att_type = $req->{attributes}->{$param}->[0];
my $att_desc = $req->{attributes}->{$param}->[1];
if ($att_type eq 'cv') {
$html .= "<li><b>$att</b> (controlled vocabulary)</li><p>";
$html .= "This parameter value can be chosen from the following (the first being default):</p><ul style='list-style: none;'>";
foreach my $cvitem (@$att_desc) {
$html .= "<li><b>".$cvitem->[0]."</b> - ".$cvitem->[1]."</li>";
}
$html .= "</ul><br>";
} else {
while (ref($att_desc) eq 'ARRAY') {
if ($att_type =~ /object/) {
$att_obj = $att_desc->[0];
} elsif (($att_type =~ /hash/) && ref($att_desc) eq 'ARRAY') {
$att_hash = $att_desc->[0];
} else {
my $att_plural = $att_desc->[0];
$att_plural =~ s/y$/ie/;
$att_type .= " of ".$att_plural."s";
}
$att_desc = $att_desc->[1];
}
$html .= "<li><b>$att</b> ($att_type)</li><p>";
if ($att_obj) {
$html .= "This attribute has an object structure:</p><ul style='list-style: none;'>";
foreach my $key (sort keys(%$att_obj)) {
my $obj_type = $att_obj->{$key}->[0];
my $obj_att = $att_obj->{$key}->[1];
my $obj_cv;
while (ref($obj_att) eq 'ARRAY') {
if ($obj_type eq 'cv') {
$obj_cv = $obj_att;
$obj_type = "controlled vocabulary";
$obj_att = "cv";
} else {
$obj_type .= " of ".$obj_att->[0]."s";
$obj_att = $obj_att->[1];
}
}
if ($obj_cv) {
$html .= "<li><b>$key ($obj_type)</b>";
$html .= "<p>This parameter value can be chosen from the following (the first being default):</p><ul style='list-style: none;'>";
foreach my $cvitem (@$obj_cv) {
$html .= "<li><b>".$cvitem->[0]."</b> - ".$cvitem->[1]."</li>";
}
$html .= "</ul><br>";
$html .= "</li>";
} else {
$html .= "<li><b>$key ($obj_type)</b> - ".$obj_att."</li>";
}
}
$html .= "</ul><br>";
} elsif ($att_hash) {
$html .= "This attribute has a hash structure:</p><ul style='list-style: none;'>";
foreach my $key (('key', 'value')) {
my $hash_type = $att_hash->{$key}->[0];
my $hash_att = $att_hash->{$key}->[1];
while (ref($hash_att) eq 'ARRAY') {
$hash_type .= " of ".$hash_att->[0]."s";
$hash_att = $hash_att->[1];
}
$html .= "<li><b>$key ($hash_type)</b> - ".$hash_att."</li>";
}
$html .= "</ul><br>";
} else {
$html .= $att_desc."</p>"
}
}
}
$html .= "<hr>";
$html .= "</p></ul>";
}
$html .= "<hr>";
}

$html .= template_end();
Expand Down Expand Up @@ -221,14 +249,15 @@ sub template_start {
<div class="navbar navbar-inverse navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="brand" href="./index.html">$site_name API documentation</a>
<a class="brand">RESTful $site_name object and resource API</a>
</div>
</div>
</div>

<div class="row" style="margin-top: 50px;">
<div name="index" class="span3" style="position: fixed; width: 130px;">
<ul class="nav nav-list">
<li><a href="#overview">back to top</a></li>
<li class="nav-header">Resources</li>
~;
}
Expand Down
4 changes: 1 addition & 3 deletions src/MGRAST/cgi/api.cgi
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#!/usr/bin/perl

use CGI;
use JSON;
use Conf;
Expand Down Expand Up @@ -236,7 +234,7 @@ else {
service => 'MG-RAST',
url => ($Conf::url_base || $cgi->url),
documentation => $cgi_url.'/api.html',
description => "RESTful Metagenomics RAST object and resource API\nFor usage note that required parameters need to be passed as path parameters, optional parameters need to be query parameters. If an optional parameter has a list of option values, the first displayed will be used as default.",
description => "The MG-RAST API covers most of the functionality available through the MG-RAST website, with access to annotations, analyses, metadata and access to the MG-RAST user inbox to view contents as well as upload files. All sequence data and data products from intermediate stages in the analysis pipeline are available for download. Other resources provide services not available through the website, e.g. the m5nr resource lets you query the m5nr database.\n\nEach query to the API is represented as a URI beginning with \"http://api.metagenomics.anl.gov/\" and has a defined structure to pass the requests and parameters to the API server.\nThe URI queries can be used from the command line, e.g. using curl, in a browser, or incorporated in a shell script or program.\n\nEach URI has the form \"http://api.metagenomics.anl.gov/{version}/{resourcepath}?{querystring}\".\nThe {version} value (currently '1') explicitly directs the request to a specific version of the API, if it is omitted the latest API version will be used.\nThe resource path is constructed from the path parameters listed below to define a specific resource and the optional query string is used to filter the results obtained for the resource.\n\ne.g. http://api.metagenomics.anl.gov/1/annotation/sequence/mgm4447943.3?evalue=10&type=organism&source=SwissProt\n\nIn this example the resource path \"annotation/sequence/mgm4447943.3\" defines a request for the annotated sequences for the MG-RAST job with ID 4447943.3.\nThe optional query string \"evalue=10&type=organism&source=SwissProt\" modifies the results by setting an evalue cutoff, annotation type and database source.\n\nThe API provides an authentication mechanism for access to private MG-RAST jobs and users' inbox. The 'auth_key' (or 'webkey') is a 25 character long string (e.g. 'j6FNL61ekNarTgqupMma6eMx5') which is used by the API to identify an MG-RAST user account and determine access rights to metagenomes. Note that the auth_key is valid for a limited time after which queries using the key will be rejected. You can create a new auth_key or view the expiration date and time of an existing auth_key on the MG-RAST website. An account can have only one valid auth_key and creating a new key will invalidate an existing key.\n\nAll public data in MG-RAST is available without an auth_key. All API queries for private data which either do not have an auth_key or use an invalid or expired auth_key will get a \"insufficient permissions to view this data\" response.\n\nThe auth_key can be included in the query string like:\nhttp://api.metagenomics.anl.gov/1/annotation/sequence/mgm4447943.3?evalue=10&type=organism&source=SwissProt&auth_key=j6FNL61ekNarTgqupMma6eMx5\nor in a request using curl like:\ncurl -X GET -H \"auth: j6FNL61ekNarTgqupMma6eMx5\" \"http://api.metagenomics.anl.gov/1/annotation/sequence/mgm4447943.3?evalue=10&type=organism&source=SwissProt\"\n\nNote that for the curl command the quotes are necessary for the query to be passed to the API correctly.\n\nIf an optional parameter passed through the query string has a list of values only the first will be used. When multiple values are required, e.g. for multiple md5 checksum values, they can be passed to the API like:\ncurl -X POST -d '{\"data\":[\"000821a2e2f63df1a3873e4b280002a8\",\"15bf1950bd9867099e72ea6516e3d602\"]}' \"http://api.metagenomics.anl.gov/m5nr/md5\"\n\nIn some cases, the data requested is in the form of a list with a large number of entries. In these cases the limit and offset parameters can be used to step through the list,\ne.g. http://api.metagenomics.anl.gov/1/project?order=name&limit=20&offset=100\nwill limit the number of entries returned to 20 with an offset of 100. If these parameters are not provided default values of limit=10 and offset=0 are used. The returned JSON structure will contain the 'next' and 'prev' (previous) URIs to simplify stepping through the list.\n\nThe data returned may be plain text, compressed gzipped files or a JSON structure.\n\nMost API queries are 'synchronous' and results are returned immediately. Some queries may require a substantial time to compute results, in these cases you can select the asynchronous option by adding '&asynchronous=1' to the end of the query string. This query will then return a URL which will return the query results when they are ready.",
contact => 'mg-rast@mcs.anl.gov',
resources => \@res };
print $cgi->header(-type => 'application/json',
Expand Down
Loading