source api

Source Browsing API

• Name: source
• Returns: text/html; charset=utf-8
• URI Template Variables: {dist}, {version}
• Availability: API Server

Returns HTML listing the contents of a distribution release. Each file and directory is a link, so that users can drill down to examine the contents in detail. This API, unlike the others, is designed primarily for use in a browser, for users who want to look at a distribution's contents without having to download and unzip it themselves. Some examples:

• italian_fts 1.2.1
• pair 0.1.2
• semver 0.2.1

Media Types

In order to make browsing the contents of a distribution as safe as possible, certain files will be served as with the text/plain media type rather than a native type. Others are changed just so that they'll be easier to load into a browser, and because files available from this API are designed for viewing rather than execution. The rules for what files are changed to be served as text/plain are:

• Files whose media types normally contain the following strings:
  • html
  • x-c
  • xml
  • calendar
  • vcard
• Files that end with the following file name suffixes:
  • .bat
  • .css
  • .eml
  • .js
  • .json
  • .mime
  • .swf

If you notice any other files serving executable media types that should not, please file a bug report.

Perl Example

Assuming you have retrieved the JSON document from the index API and stored the data in the $table hash, you can fetch the HTML listing the contents of version 1.1.0 of the "pair" distribution like so:

use URI::Template;
use HTTP::Tiny;
my $tmpl = URI::Template->new($table->{source});
my $uri = $tmpl->process({
    dist    => 'pair',
    version => '1.1.0',
});

my $req  = HTTP::Tiny->new;
my $res  = $req->get('https://api.pgxn.org' . $uri);
say $res->{content};