RESTful Application Programming Interface (API)

The REST API allows third-party applications to retrive data stored within BIGSdb databases or to send new submissions to database curators. To use the REST API, your application will make a HTTP request and parse the response. The response format is JSON (except for routes that request a FASTA or CSV file).

Access to protected resources, i.e. those requiring an account, can be accessed via the API using OAuth authentication.

Passing additional/optional parameters

If you are using a method called with GET, optional parameters can be passed as arguments to the query URL by adding a ‘?’ followed by the first argument and its value (separated by a ‘=’). Additional parameters are separated by a ‘&’, e.g.

https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates?page=2&page_size=100

Methods called with POST require their arguments to be sent as JSON within the post body.

Paging using request headers

Paging of results can be selected using query parameters as described above. In this case, methods that support paging will include a paging object in the JSON response. This will contain links to the next page, last page etc.

The API also supports paging using request headers. The following request headers are supported:

  • X-OFFSET

  • X-PER-PAGE

e.g.

curl -i -H "X-PER-PAGE:10" -H "X-OFFSET:0" https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates

If either of these headers are used, the paging object is no longer returned as part of the JSON response. The response will include the following headers:

  • X-OFFSET

  • X-PER-PAGE

  • X-TOTAL-PAGES

Resources

GET / or /db - List site resources

Required route parameters: None

Optional query parameters: None

Example request URI: https://rest.pubmlst.org/

Response: List of resource groupings (ordered by name). Groups may consist of paired databases for sequence definitions and isolate data, or any set of related resources. Each group contains:

  • name [string] - short name (usually a single word)

  • description [string] - fuller description

  • databases [array] - list of database objects, each consists of three key/value pairs:

    • name [string] - name of database config

    • description [string] - short description of resource

    • href [string] - URI to access resource

GET /db/{database} - List database resources

These will vary depending on whether the resource is an isolate or a sequence definition database.

Required route parameter: database [string] - Database configuration name

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates

Response: Object containing a subset of the following key/value pairs:

  • fields [string] - URI to isolate provenance field information

  • isolates [string] - URI to isolate records

  • genomes [string] - URI to genome records

  • schemes [string] - URI to list of schemes

  • loci [string] - URI to list of loci

  • projects [string] - URI to list of projects

GET /db/{database}/classification_schemes - List classification schemes

Required route parameter: database [string] - Database configuration name

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/classification_schemes

Response: Object containing:

GET /db/{database}/classification_schemes/{classification_scheme_id} - Retrieve classification scheme information and groups

Required route parameters:

  • database [string] - Database configuration name

  • classification_scheme_id [integer] - Classification scheme id number

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/classification_schemes/1

Response: Object containing some or all of:

  • id [integer] - Classification scheme id

  • name [text] - Name of classification scheme

  • description [text] - Description of classification scheme

  • relative_threshold [boolean] - True if a relative thresold is used

  • inclusion_threshold [integer] - The threshold for number of loci difference used to group

  • groups [string] (sequence definition databases only) - URI to list of groups

    • id [integer] - group id

    • profiles [array] - list of URIs to profiles belonging to the group

GET /db/{database}/classification_schemes/{classification_scheme_id}/groups - List groups defined for a classification scheme

Sequence definition databases only.

Required route parameters:

  • database [string] - Database configuration name

  • classification_scheme_id [integer] - Classification scheme id number

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

  • records [integer] - Number of groups

  • groups [array] - List of URIs to classification group records.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/classification_schemes/{classification_scheme_id}/groups/{group_id} - List isolates or profiles belonging to a classification scheme group

Required route parameters:

  • database [string] - Database configuration name

  • classification_scheme_id [integer] - Classification scheme id number

  • group_id [integer] - Group id number

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/classification_schemes/4/groups/65

Response: Object containing some of:

  • records [integer] - Number of isolates or profiles

  • isolates (isolate database only) [array] - List of URIs to isolate records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • profiles (sequence definition databases only) [array] - List of URIs to profile records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/loci - List loci

Required route parameter: database [string] - Database configuration name

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

  • alleles_added_after [date] - Include only loci with alleles added after (but not on) specified date (ISO 8601 format). Only recognized in sequence definition databases.

  • alleles_updated_after [date] - Include only loci with alleles last modified after (but not on) specified date (ISO 8601 format). Only recognized in sequence definition databases.

  • alleles_added_reldate [integer] - Include only loci with alleles added within the number of days specified. Only recognized in sequence definition databases.

  • alleles_updated_reldate [integer] - Include only loci with alleles last modified within the number of days specified. Only recognized in sequence definition databases.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/loci

Response: Object containing:

  • records [integer] - Number of loci

  • loci [array] - List of URIs to defined locus records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

Note

See also the scheme specific version, allowing filtering by date of last allele update for just the loci that are members of a scheme.

GET /db/{database}/loci/{locus} - Retrieve locus record

Provides information about a locus, including links to allele sequences (in seqdef databases).

Required route parameters:

  • database [string] - Database configuration name

  • locus [string] - Locus name

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/loci/abcZ

Response: Object containing a subset of the following key/value pairs:

  • id [string] - locus name

  • data_type [string] - ‘DNA’ or ‘peptide’

  • allele_id_format [string] - ‘integer’ or ‘text’

  • allele_id_regex [string] - regular expression constraining allele ids

  • common_name [string]

  • aliases [array] - list of alternative names of the locus

  • length_varies [boolean]

  • length [integer] - length if alleles are of a fixed length

  • coding_sequence [boolean]

  • orf [integer] - 1-6

  • schemes [array] - list of scheme objects, each consisting of:

    • scheme [string] - URI to scheme information

    • description [string]

  • min_length [integer] (seqdef databases) - minimum length for variable length loci

  • max_length [integer] (seqdef databases) - maximum length for variable length loci

  • alleles [string] (seqdef databases) - URI to list of allele records

  • alleles_fasta [string] (seqdef databases) - URI to FASTA file of all alleles of locus

  • curators [array] (seqdef databases) - list of URIs to user records of curators of the locus

  • publications [array] (seqdef databases) - list of PubMed id numbers of papers describing the locus

  • full_name [string] (seqdef databases)

  • product [string] (seqdef databases)

  • description [string] (seqdef databases)

  • extended_attributes [array] (seqdef databases) - list of extended attribute objects. Each consists of a subset of the following fields:

    • field [string] - field name

    • value_format [string] - ‘integer’, ‘text’, or ‘boolean’

    • value_regex [string] - regular expression constraining value

    • description [string] - description of field

    • length [integer] - maximum length of field

    • required [boolean]

    • allowed_values [array] - list of allowed values

  • genome_position [integer] (isolate databases)

GET /db/{database}/loci/{locus}/alleles - Retrieve list of alleles defined for a locus

Required route parameters:

  • database [string] - Database configuration name

  • locus [string] - Locus name

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

  • added_after [date] - Include only alleles added after (but not on) specified date (ISO 8601 format).

  • added_reldate [integer] - Include only alleles added within the specified number of days.

  • added_on [date] - Include only alleles added on specified date (ISO 8601 format).

  • updated_after [date] - Include only alleles last modified after (but not on) specified date (ISO 8601 format).

  • updated_reldate [integer] - Include only alleles updated within the specified number of days.

  • updated_on [date] - Include only alleles last modified on specified date (ISO 8601 format).

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/loci/abcZ/alleles

Response: Object containing:

  • records [integer] - Number of alleles.

  • last_updated [date] - Latest allele addition/modification date (ISO 8601 format).

  • alleles [array] - List of URIs to defined allele records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/loci/{locus}/alleles_fasta - Download alleles in FASTA format

Required route parameters:

  • database [string] - Database configuration name

  • locus [string] - Locus name

Optional parameters:

  • added_after [date] - Include only alleles added after (but not on) specified date (ISO 8601 format).

  • added_reldate [integer] - Include only alleles added within the specified number of days.

  • added_on date] - Include only alleles added on specified date (ISO 8601 format).

  • updated_after [date] - Include only alleles last modified after (but not on) specified date (ISO 8601 format).

  • updated_reldate [integer] - Include only alleles last modified within the specified number of days.

  • updated_on [date] - Include only alleles last modified on specified date (ISO 8601 format).

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/loci/abcZ/alleles_fasta

Response: FASTA format file of allele sequences

GET /db/{database}/loci/{locus}/alleles/{allele_id} - Retrieve full allele information

Required route parameters:

  • database [string] - Database configuration name

  • locus [string] - Locus name

  • allele_id [string] - Allele identifier

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/loci/abcZ/alleles/5

Response: Object containing the following key/value pairs:

  • locus [string] - URI to locus description

  • allele_id [string] - allele identifier

  • sequence [string] - sequence

  • status [string] - either ‘Sanger trace checked’, ‘WGS: manual extract’, ‘WGS: automated extract’, or ‘unchecked’

  • sender [string] - URI to user details of sender

  • curator [string] - URI to user details of curator

  • date_entered [string] - record creation date (ISO 8601 format)

  • datestamp [string] - last updated date (ISO 8601 format)

POST /db/{database}/loci/{locus}/sequence - Query sequence to identify allele

Required route parameters:

  • database [string] - Database configuration name

  • locus [string] - Locus name

Required additional parameters (JSON-encoded in POST body):

  • sequence [string] - Sequence string or base64-encoded FASTA file

Optional parameters (JSON-encoded in POST body):

  • details [true/false] - Return detailed exact match parameters

  • base64 [true/false] - Sequence is a base64-encoded FASTA file

Response: Object containing the following key/value pairs:

  • exact_matches [array] - list of match objects, each consisting of:

    additionally if ‘details’ parameter passed:

    • start - start position on query

    • end - end position on query

    • orientation - forward/reverse

    • length - length of matched allele

    • contig - contig name if FASTA file is uploaded

    If the locus is linked to field data in client isolate databases, there may also be an object called ‘linked_data’ containing values and frequencies of the field for the returned allele.

  • best_match [object] - consisting of key/value pairs (if no exact matches)

    • allele_id

    • href - URI to allele record.

    • start - start position on query (predicted taking account of allele length)

    • end - end position on query (predicted taking account of allele length)

    • orientation - forward/reverse

    • length - length of matched allele

    • alignment - length of BLAST alignment

    • mismatches - number of mismatches

    • identity - %identity of match

    • gaps - number of gaps in alignment

POST /db/{database}/sequence - Query sequence to identify allele without specifying locus

Required route parameters:

  • database [string] - Database configuration name

Required additional parameters (JSON-encoded in POST body):

  • sequence [string] - Sequence string or base64-encoded FASTA file

Optional parameters (JSON-encoded in POST body):

  • details [true/false] - Return detailed exact match parameters

  • base64 [true/false] - Sequence is a base64-encoded FASTA file

Response:

  • exact_matches [object] consisting of locus keys, each consisting of array of match objects consisting of:

    additionally if ‘details’ parameter passed:

    • start - start position on query

    • end - end position on query

    • orientation - forward/reverse

    • length - length of matched allele

    • contig - contig name if FASTA file is uploaded

    If the locus is linked to field data in client isolate databases, there may also be an object called ‘linked_data’ containing values and frequencies of the field for the returned allele.

Note

This method only supports exact matches. If no match is indicated for a specific locus, use the locus-specific call to identify the closest match.

GET /db/{database}/sequences - Get summary of defined sequences

Required route parameter: database [string] - Database configuration name

Optional parameters:

  • added_after [date] - Count only alleles added after (but not on) specified date (ISO 8601 format).

  • added_reldate [integer] - Count only alleles added within the specified number of days.

  • added_on [date] - Count only alleles added on specified date (ISO 8601 format).

  • updated_after [date] - Count only alleles last modified after (but not on) specified date (ISO 8601 format).

  • updated_reldate [integer] - Count only alleles last modified within the specified number of days.

  • updated_on [date] - Count only allele updated on specified date (ISO 8601 format).

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/sequences

Response: Object containing a subset of the following key/value pairs:

  • loci [string] - URI to list of loci

  • records [integer] - Number of alleles defined

  • last_updated [date] - Latest allele addition/modification date (ISO 8601 format).

GET /db/{database}/schemes - List schemes

Required route parameter: database [string] - Database configuration name

Optional parameters:

  • with_pk [integer] - Set to non-zero value to only show indexed schemes, i.e. those with a primary key field that defines each unique combination of alleles, e.g. MLST.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes

Response:

  • records [integer] - Number of schemes

  • schemes [array] - list of scheme objects, each containing:

GET /db/{database}/schemes/{scheme_id} - Retrieve scheme information

Includes links to allelic profiles (in seqdef databases, if appropriate). Required route parameters:

  • database [string] - Database configuration name

  • scheme_id [integer] - Scheme id number

Optional parameters:

  • added_after [date] - Count only profiles added after (but not on) specified date (ISO 8601 format).

  • added_reldate [integer] - Count only profiles added within the specified number of days.

  • added_on [date] - Count only profiles added on specified date (ISO 8601 format).

  • updated_after [date] - Count only profiles last modified after (but not on) specified date (ISO 8601 format).

  • updated_reldate [integer] - Count only profiles last modified within the specified number of days.

  • updated_on [date] - Count only profiles updated on specified date (ISO 8601 format).

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/1

Response: Object containing a subset of the following key/value pairs:

  • id [integer]

  • description [string]

  • locus_count [integer] - number of loci belonging to scheme

  • loci [array] - list of URIs to locus descriptions

  • has_primary_key_field [boolean]

  • fields [array] - list of URIs to scheme field descriptions

  • primary_key_field [string] - URI to primary key field description

  • profiles [string] - URI to list of profile definitions (only seqdef databases)

  • profiles_csv [string] - URI to tab-delimited file of all scheme profiles

  • curators [array] (seqdef databases) - list of URIs to user records of curators of the scheme

  • records [integer] - Number of profiles

  • last_added [date] - Latest profile addition/modification date (ISO 8601 format).

  • last_updated [date] - Latest profile addition/modification date (ISO 8601 format).

GET /db/{database}/schemes/{scheme_id}/loci - Retrieve scheme loci

Required route parameters:

  • database [string] - Database configuration name

  • scheme_id [integer] - Scheme id number

Optional parameters:

  • alleles_added_after [date] - Include only loci with alleles added after (but not on) specified date (ISO 8601 format). Only recognized in sequence definition databases.

  • alleles_added_reldate [integer] - Include only loci with alleles added within the specified number of days. Only recognized in sequence definition databases.

  • alleles_updated_after [date] - Include only loci with alleles last modified after specified date (ISO 8601 format). Only recognized in sequence definition databases.

  • alleles_updated_reldate [integer] - Include only loci with alleles last modified within the specified number of days. Only recognized in sequence definition databases.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/1/loci

Response: Object containing:

GET /db/{database}/schemes/{scheme_id}/fields/{field} - Retrieve information about scheme field

Required route parameters:

  • database [string] - Database configuration name

  • scheme_id [integer] - Scheme id number

  • field [string] - Field name

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/1/fields/ST

Response: Object containing the following key/value pairs:

  • field [string] - field name

  • type [string] - data type of field (integer or text)

  • primary_key [boolean] - true if field is the scheme primary key

GET /db/{database}/schemes/{scheme_id}/profiles - List allelic profiles defined for scheme

Required route parameters:

  • database [string] - Database configuration name

  • scheme_id [integer] - Scheme id

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

  • added_after [date] - Include only profiles added after (but not on) specified date (ISO 8601 format).

  • added_reldate [integer] - Include only profiles added within the specified number of days.

  • added_on [date] - Include only profiles added on specified date (ISO 8601 format).

  • updated_after [date] - Include only profiles last modified after (but not on) specified date (ISO 8601 format).

  • updated_reldate [integer] - Include only profiles last modified within the specified number of days.

  • updated_on [date] - Include only profiles last modified on specified date (ISO 8601 format).

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/1/profiles

Response: Object containing:

  • records [integer] - Number of profiles

  • last_updated [date] - Latest profile addition/modification date (ISO 8601 format).

  • profiles [array] - List of URIs to defined profile records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

Note

This method also supports content negotiation. If the request accepts header includes TSV or CSV, then the call is redirected to /db/{database}/schemes/{scheme_id}/profiles_csv.

GET /db/{database}/schemes/{scheme_id}/profiles_csv - Download allelic profiles in CSV (tab-delimited) format

Required route parameters:

  • database [string] - Database configuration name

  • scheme_id [integer] - Scheme id

Optional parameters:

  • added_after [date] - Include only profiles added after (but not on) specified date (ISO 8601 format).

  • added_reldate [integer] - Include only profiles added within the specified number of days.

  • added_on [date] - Include only profiles added on specified date (ISO 8601 format).

  • updated_after [date] - Include only profiles last modified after (but not on) specified date (ISO 8601 format).

  • updated_reldate [integer] - Include only profiles last modified within the specified number of days.

  • updated_on [date] - Include only profiles last modified on specified date (ISO 8601 format).

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/1/profiles_csv

Response: Tab-delimited text file of allelic profiles

GET /db/{database}/schemes/{scheme_id}/profiles/{profile_id} - Retrieve allelic profile record

Required route parameters:

  • database [string] - Database configuration name

  • scheme_id [integer] - Scheme id

  • profile_id [string/integer] - Profile id

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/1/profiles/11

Response: Object containing the following key/value pairs:

  • primary_key_term [string/integer] - The field name is the primary key, e.g. ST. The value is the primary key value (primary_id used as an argument).

  • alleles [object] - list of URIs to allele descriptions

  • other_scheme_fields [string/integer] - Each scheme field will have its own value if defined. The field name is the name of the field.

  • sender [string] - URI to user details of sender

  • curator [string] - URI to user details of curator

  • date_entered [string] - record creation date (ISO 8601 format)

  • datestamp [string] - last updated date (ISO 8601 format)

POST /db/{database}/schemes/{scheme_id}/sequence - Query sequence to extract allele designations/fields for a scheme

Required route parameters:

  • database [string] - Database configuration name

  • scheme_id [integer] - Scheme id

Required additional parameters (JSON-encoded in POST body):

  • sequence [string] - Sequence string or base64-encoded FASTA file

Optional parameters (JSON-encoded in POST body):

  • details [true/false] - Return detailed exact match parameters

  • base64 [true/false] - Sequence is a base64-encoded FASTA file

Response: Object containing the following key/value pairs:

  • exact_matches [array] - list of match objects, each consisting of:

    additionally if ‘details’ parameter passed:

    • start - start position on query

    • end - end position on query

    • orientation - forward/reverse

    • length - length of matched allele

    • contig - contig name if FASTA file is uploaded

    If the locus is linked to field data in client isolate databases, there may also be an object called ‘linked_data’ containing values and frequencies of the field for the returned allele.

Example curl call to upload a FASTA file ‘contigs.fasta’ and extract MLST results from Neisseria database:

(echo -n '{"base64":true,"sequence": "'; base64 contigs.fasta; echo '"}') |
curl -s -H "Content-Type: application/json" -X POST "https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/1/sequence" -d @-

Note

This method only supports exact matches. If no match is indicated for a specific locus, use the locus-specific call to identify the closest match.

POST /db/{database}/schemes/{scheme_id}/designations - Query allelic profile to extract fields for a scheme

Required route parameters:

  • database [string] - Database configuration name

  • scheme_id [integer] - Scheme id

Required additional parameters (JSON-encoded in POST body):

  • designations [object] - consisting of

    • locus objects each containing an array of alleles (see example)

Response: Object containing the following key/value pairs:

  • exact_matches [object] - consisting of locus values, each consisting of an array of allele values:

    • allele_id [string]

    If the locus is linked to field data in client isolate databases, there may also be an object called ‘linked_data’ containing values and frequencies of the field for the returned allele.

  • fields [object] - consisting of key/value pairs of scheme fields (if defined)

Example curl call to query an allelic profile and extract MLST results from Neisseria database:

curl -s -H "Content-Type: application/json" -X POST "https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/schemes/1/designations" -d '{"designations":{"abcZ":[{"allele":"2"}],"adk":[{"allele":"3"}],"aroE":[{"allele":"4"}],"fumC":[{"allele":"3"}],"gdh":[{"allele":"8"}],"pdhC":[{"allele":"4"}],"pgm":[{"allele":"6"}]}}'

GET /db/{database}/isolates - Retrieve list of isolate records

Required route parameter: database [string] - Database configuration name

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

  • added_after [date] - Include only isolates added after (but not on) specified date (ISO 8601 format).

  • added_reldate [integer] - Include only isolates added within the specified number of days.

  • added_on [date] - Include only isolates added on specified date (ISO 8601 format).

  • include_old_versions [integer] - Set to 1 to include old record versions (the default is to only include new versions)

  • updated_after [date] - Include only isolates last modified after (but not on) specified date (ISO 8601 format).

  • updated_reldate [integer] - Include only isolates last modified within the specified number of days.

  • updated_on [date] - Include only isolates updated on specified date (ISO 8601 format).

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates

Response: Object containing:

  • records [integer] - Number of isolates

  • isolates [array] - List of URIs to isolate records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/isolates/{isolate_id} - Retrieve isolate record

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

Optional parameter:

  • provenance_only [integer] - Set to non-zero value to only return provenance metadata

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1

Response: Object containing some or all of the following key/value pairs:

  • provenance [object] - set of key/value pairs. Keys are defined by calling the /fields route route. The fields will vary by database but will always contain the following:

    • id [integer]

    • sender [string] - URI to user details of sender

    • curator [string] - URI to user details of curator

    • date_entered [string] - record creation date (ISO 8601 format)

    • datestamp [string] - last updated date (ISO 8601 format)

  • publications [array] (seqdef databases) - list of PubMed id numbers of papers that refer to the isolate

  • sequence_bin [object] - consists of the following key/value pairs:

  • allele_designations [object] - consists of the following key/value pairs:

  • schemes [array] - list of scheme objects, each containing some of the following:

    • description [string] - description of scheme

    • loci_designated_count [integer] - number of loci within scheme that have an allele designated for this isolate.

    • allele_ids [string] - URI to list of all allele_id values defined for this scheme for this isolate

    • full_designations [string] - URI to list of full allele designation records for this isolate

    • fields [object] - consisting of key/value pairs where the key is the name of each scheme field

    • classification_schemes [object] - consisting of key/value pairs, where each key is the name of the classification scheme and the value is an object consisting of:

      • href [string] - URI to classification scheme description

      • groups [array] - list of group objects consisting of:

        • group [integer] - group id

        • records [integer] - number of isolates in group

        • isolates [string] - URI to classification group record containing URIs to member isolate records

  • projects [array] - list of project objects, each containing the following:

  • history [string] - URI to isolate history record

  • new_version [string] - URI to newer version of record

  • old_version [string] - URI to older version of record

GET /db/{database}/isolates/{isolate_id}/allele_designations - Retrieve list of allele designation records

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1/allele_designations

Response: Object containing:

  • records [integer] - Number of allele designations

  • allele_designations [array] - List of URIs to allele designation records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/isolates/{isolate_id}/allele_designations/{locus} - Retrieve full allele designation record

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

  • locus [string] - Locus name

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1/allele_designations/BACT000065

Response: List of allele_designation objects (there may be multiple designations for the same locus), each containing:

  • locus [string] - URI to locus description

  • allele_id [string]

  • method [string] - either ‘manual’ or ‘automatic’

  • status [string] - either ‘confirmed’ or ‘provisional’

  • comments [string]

  • sender [string] - URI to user details of sender

  • curator [string] - URI to user details of curator

  • datestamp [string] - last updated date (ISO 8601 format)

GET /db/{database}/isolates/{isolate_id}/allele_ids - Retrieve allele identifiers

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1/allele_ids

Response: Object containing:

  • records [integer] - Number of allele id objects

  • allele_ids [array] - List of allele id objects, each consisting of a key/value pair where the key is the locus name. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/isolates/{isolate_id}/schemes/{scheme_id}/allele_designations - Retrieve scheme allele designation records

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

  • scheme_id [integer] - Scheme identifier

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1/schemes/1/allele_designations

Response:

  • records [integer] - Number of allele designation objects

  • allele_designations [array] - List of allele designation objects for each locus in the specified scheme that has been designated.

GET /db/{database}/isolates/{isolate_id}/schemes/{scheme_id}/allele_ids - Retrieve list of scheme allele identifiers

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

  • scheme_id [integer] - Scheme identifier

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1/schemes/1/allele_ids

Response:

  • records [integer] - Number of allele id objects

  • allele_ids [array] - List containing allele id objects for each locus in the specified scheme that has been designated. Each allele_id object contains a key which is the name of the locus with a value that may be either a string, integer or array of strings or integers (required where there are multiple designations for a locus). The data type depends on the allele_id_format set for the specific locus.

GET /db/{database}/isolates/{isolate_id}/contigs - Retrieve list of contigs

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1/contigs

Response: Object containing:

  • records [integer] - Number of contigs

  • contigs [array] - List of URIs to contig records Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/isolates/{isolate_id}/contigs_fasta - Download contigs in FASTA format

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

Optional parameter:

  • header [string] - either ‘original_designation’ or ‘id’ (default is ‘id’). This selects whether the FASTA header lines contain the originally uploaded FASTA headers or the sequence bin id numbers.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1/contigs_fasta?header=original_designation

Response: FASTA format file of isolate contig sequences

GET /db/{database}/isolates/{isolate_id}/history - Retrieve isolate update history

Required route parameters:

  • database [string] - Database configuration name

  • isolate_id [integer] - Isolate identifier

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/1/history

Response: Object containing:

  • records [integer] - Number of updayes

  • contigs [array] - List of update objects each consisting of the following key/value pairs:

    • curator [string] - URI to user details of curator

    • timestamp [string] - Time of update

    • actions [array] - List of update descriptions [strings]

GET /db/{database}/genomes - Retrieve list of isolate records that have genome assemblies

Required route parameter: database [string] - Database configuration name

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

  • added_after [date] - Include only isolates added after (but not on) specified date (ISO 8601 format).

  • added_reldate [integer] - Include only isolates added within the specified number of days.

  • added_on [date] - Include only isolates added on specified date (ISO 8601 format).

  • include_old_versions [integer] - Set to 1 to include old record versions (the default is to only include new versions)

  • updated_after [date] - Include only isolates last modified after (but not on) specified date (ISO 8601 format).

  • updated_reldate [integer] - Include only isolates last modified within the specified number of days.

  • updated_on [date] - Include only isolates updated on specified date (ISO 8601 format).

  • genome_size [integer] - Filter to only include records with a sequence bin of at least the specified size (default is 500,000bp).

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/genomes

Response: Object containing:

  • records [integer] - Number of isolates

  • isolates [array] - List of URIs to isolate records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

POST /db/{database}/isolates/search - Search isolate database

Required route parameters:

  • database [string] - Database configuration name

Optional parameters (appended to URI):

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

Query parameters (JSON-encoded in POST body):

You must include at least one query parameter.

Parameter names in the following forms are supported:

  • field.{field} - key/value pairs for provenance fields. Supported field names can be found by calling the /fields route. The fields will vary by database.

  • locus.{locus} - key/value pairs of locus and its allele designation. Supported locus names can be found by calling the /loci route.

  • scheme.{scheme_id}.{scheme_field} - key/value pairs of scheme fields and their values. Supported field names can be determined by following routes from the /schemes route.

Example method call using curl: The following searches for Neisseria ST-11 isolates from Europe in 2015 (MLST is scheme#1 in this database).

curl -s -H "Content-Type: application/json" -X POST \
"https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/isolates/search" \
-d '{"field.continent":"europe","field.year":2015,"scheme.1.ST":11}'

Response: Object containing:

  • records [integer] - Number of isolates

  • isolates [array] - List of URIs to isolate records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/contigs/{contig_id} - Retrieve contig record

Required route parameters:

  • database [string] - Database configuration name

  • contig_id [integer] - Contig identifier

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/contigs/180062

Response: Contig object consisting of the following key/value pairs:

  • id [integer] - contig identifier

  • isolate_id [integer] - isolate identifier

  • sequence [string] - contig sequence

  • length [integer] - length of contig sequence

  • method [string] - sequencing method

  • sender [string] - URI to user details of sender

  • curator [string] - URI to user details of curator

  • date_entered [string] - record creation date (ISO 8601 format)

  • datestamp [string] - last updated date (ISO 8601 format)

  • loci [array] - list of sequence tag objects consisting of:

    • locus [string] - URI to locus description

    • locus_name [string]

    • start [integer]

    • end [integer]

    • direction [string] - forward/reverse

    • complete [boolean] - true/false

GET /db/{database}/fields - Retrieve list of isolate provenance field descriptions

Required route parameters:

  • database [string] - Database configuration name

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/fields

Response: Array of field objects, each consisting of some or all of the following key/value pairs:

  • name [string] - name of field

  • type [string] - data type (int, text, date, float)

  • length [integer] - maximum length of field

  • required [boolean] - true if field value is required

  • min [integer] - minimum value for integer values

  • max [integer] - maximum value for integer values

  • regex [string] - regular expression that constrains the allowed value of the field

  • comments [string]

  • allowed values [array] - list of allowed values for the field

  • values [string] - URI to list of used field values

GET /db/{database}/fields/{field} - Retrieve values set for a provenance field

Required route parameters:

  • database [string] - Database configuration name

  • field [string] - Provenance metadata field name

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/fields/country

Response: Object containing:

  • records [integer] - Number of values

  • values [array] - List of values used in isolate records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/users/{user_id} - Retrieve user information

Users may be data submitters or curators.

Required route parameters:

  • database [string] - Database configuration name

  • user_id [integer] - User id number

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/users/2

Response: Object containing the following key/value pairs:

  • id [integer] - user id number

  • first_name [string]

  • surname [string]

  • affiliation [string] - institutional affiliation

  • email [string] - E-mail address (may be hidden depending on server configuration)

GET /db/{database}/curators - Retrieve list of curators

Required route parameters:

  • database [string] - Database configuration name

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/curators

Response: Object containing:

GET /db/{database}/projects - Retrieve list of projects

Required route parameter: database [string] - Database configuration name

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/projects

Response:

  • projects [array] - List of project objects, each containing:

GET /db/{database}/projects/{project_id} - Retrieve project information

Required route parameters:

  • database [string] - Database configuration name

  • project_id [integer] - Project id number

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/projects/3

Response: Object containing a subset of the following key/value pairs:

GET /db/{database}/projects/{project_id}/isolates - Retrieve list of isolates belonging to a project

Required route parameter:

  • database [string] - Database configuration name

  • project_id [integer] - Project id number

Optional parameters:

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/projects/3/isolates

Response: Object containing:

  • records [integer] - Number of isolates in the project

  • isolates [array] - List of URIs to isolate records. Pages are 100 records by default. Page size can be modified using the page_size parameter.

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

GET /db/{database}/submissions - retrieve list of submissions

Required route parameter: database [string] - Database configuration name

Optional parameters:

  • type [string] - either ‘alleles’, ‘profiles’ or ‘isolates’

  • status [string] - either ‘closed’ or ‘pending’

  • page [integer]

  • page_size [integer]

  • return_all [integer] - Set to non-zero value to disable paging.

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_isolates/submissions

Response: Object containing:

  • records [integer] - Number of submissions

  • submissions [array] - List of URIs to submission records

  • paging [object] - Some or all of the following:

    • previous - URI to previous page of results

    • next - URI to next page of results

    • first - URI to first page of results

    • last - URI to last page of results

    • return_all - URI to page containing all results (paging disabled)

POST /db/{database}/submissions - create new submission

Required route parameter: database [string] - Database configuration name

Required additional parameters (JSON-encoded in POST body):

  • type [string] - either:

    • alleles (sequence definition databases only)

    • profiles (sequence definition databases only)

    • isolates (isolate databases only)

    • genomes (isolate databases only)

The following are required with the specified database type:

Allele submissions

  • locus [string] - name of locus

  • technology [string] - name of sequencing technology: either ‘454’, ‘Illumina’, ‘Ion Torrent’, ‘PacBio’, ‘Oxford Nanopore’, ‘Sanger’, ‘Solexa’, ‘SOLiD’, or ‘other’

  • read_length [string] - read length of sequencing: either ‘<100’, ‘100-199’, ‘200-299’, ‘300-499’, ‘>500’, or any positive integer (only required for Illumina)

  • coverage [string] - mean coverage of sequencing: either ‘<20x’, ‘20-49x’, ‘50-99x’, ‘>100x’, or any positive integer (only required for Illumina)

  • assembly [string] - assembly method: either ‘de novo’ or ‘mapped’

  • software [string] - name of assembly software

  • sequences [string] - either single raw sequence or multiple sequences in FASTA format

Profile submissions

  • scheme_id [integer] - scheme id number

  • profiles [string] - tab-delimited profile data - this should include a header line containing the name of each locus

Isolate submissions

  • isolates [string] - tab-delimited isolate data - this should include a header line containing each field or locus included

Genome submissions

  • isolates [string] - tab-delimited isolate data - this should include a header line containing each field or locus included as well as for ‘assembly_filename’ and ‘sequence_method’. The ‘sequence_method’ should be either ‘454’, ‘Illumina’, ‘Ion Torrent’, ‘PacBio’, ‘Oxford Nanopore’, ‘Sanger’, ‘Solexa’, ‘SOLiD’, or ‘other’. Following submission, contig files should be uploaded with the same names as set for ‘assembly_filename’. This can be done using the file upload route.

Optional parameters:

  • message [string] - correspondence to the curator

  • email [integer] - set to 1 to enable E-mail updates (E-mails will be sent to the registered user account address).

Response: Object containing:

  • submission - URI to submission record

    For genome submissions, the response object will also contain:

  • missing_files [array] - List of filenames that need to be uploaded to complete the submission. These filenames are defined in the ‘assembly_filename’ field of the isolate record upload. The files should contain the contig assemblies.

  • message [string] - ‘Please upload missing contig files to complete submission.’

GET /db/{database}/submissions/{submission_id} - Retrieve submission record

Required route parameters:

  • database [string] - Database configuration name

  • submission_id [string] - Submission id

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/submissions/BIGSdb_20151013081836_14559_14740

Response: Object containing some of the following:

  • id [string] - Submission id

  • type [string] - Either ‘alleles’, ‘profiles’, ‘isolates’

  • date_submitted [string] - Submission date (ISO 8601 format)

  • datestamp [string] - Last updated date (ISO 8601 format)

  • submitter [string] - URI to user details of submitter

  • curator [string] - URI to user details of curator

  • status [string] - either ‘started’, ‘pending’, or ‘closed’

  • outcome [string] - either ‘good’ (data uploaded), ‘bad’ (data rejected), or ‘mixed’ (parts of submission accepted)

  • correspondence [array] - List of correspondence objects in time order. Each contains:

Allele submissions

  • locus [string] - name of locus

  • technology [string] - name of sequencing technology: either ‘454’, ‘Illumina’, ‘Ion Torrent’, ‘PacBio’, ‘Oxford Nanopore’, ‘Sanger’, ‘Solexa’, ‘SOLiD’, or ‘other’

  • read_length [string] - read length of sequencing: either ‘<100’, ‘100-199’, ‘200-299’, ‘300-499’, ‘>500’, or any positive integer (only required for Illumina)

  • coverage [string] - mean coverage of sequencing: either ‘<20x’, ‘20-49x’, ‘50-99x’, ‘>100x’, or any positive integer (only required for Illumina)

  • assembly [string] - assembly method: either ‘de novo’ or ‘mapped’

  • software [string] - name of assembly software

  • seqs [array] - List of sequence objects each containing:

    • seq_id [string] - Sequence identifier

    • assigned_id [string] - Allele identifier if uploaded to the database (otherwise undefined)

    • status [string] - Either ‘pending’, ‘assigned’, or ‘rejected’

    • sequence [string]

Profile submissions

  • scheme [string] - URI to scheme information

  • profiles [array] - List of profile record objects. Each contains:

    • profile_id [string] - Record identifier

    • assigned_id [string] - Profile identifier if uploaded to the database (otherwise undefined)

    • status [string] - Either ‘pending’, ‘assigned’, or ‘rejected’

    • designations [object] containing key/value pairs for each locus containing the allele identifier

Isolate submissions

  • isolates [array] - List of isolate record objects. Each contains key/value pairs for included fields.

DELETE /db/{database}/submissions/{submission_id} - Delete submission record

You must be the owner and the record must be closed.

Required route parameters:

  • database [string] - Database configuration name

  • submission_id [string] - Submission id

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/submissions/BIGSdb_20151013081836_14559_14740

Response: message [string] - ‘Submission deleted.’

GET /db/{database}/submissions/{submission_id}/messages - Retrieve submission correspondence

Required route parameters:

  • database [string] - Database configuration name

  • submission_id [string] - Submission id

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/submissions/BIGSdb_20151013081836_14559_14740/messages

Response: Array of correspondence objects in time order. Each contains:

POST /db/{database}/submissions/{submission_id}/messages - Add submission correspondence

Required route parameters:

  • database [string] - Database configuration name

  • submission_id [string] - Submission id

Required additional parameter (JSON-encoded in POST body):

  • message [string] - Message text

Optional parameters: None

Response: message [string] - ‘Message added.’

GET /db/{database}/submissions/{submission_id}/files - Retrieve list of supporting files uploaded for submission

Required route parameters:

  • database [string] - Database configuration name

  • submission_id [string] - Submission id

Optional parameters: None

Example request URI: https://rest.pubmlst.org/db/pubmlst_neisseria_seqdef/submissions/BIGSdb_20151013081836_14559_14740/files

Response: Array of URIs to files

POST /db/{database}/submissions/{submission_id}/files - Upload submission supporting file

Required route parameters:

  • database [string] - Database configuration name

  • submission_id [string] - Submission id

Required additional parameters (JSON-encoded in POST body):

  • filename [string] - Name of file to store within submission

  • upload [base64 encoded data] - Raw file data

Optional parameters: None

Response: message [string] - ‘File uploaded.’

GET /db/{database}/submissions/{submission_id}/files/{filename} - Download submission supporting file

Required route parameters:

  • database [string] - Database configuration name

  • submission_id [string] - Submission id

  • filename [string] - Name of file

Optional parameters: None

Response: File download

DELETE /db/{database}/submissions/{submission_id}/files/{filename} - Delete submission supporting file

Required route parameters:

  • database [string] - Database configuration name

  • submission_id [string] - Submission id

  • filename [string] - Name of file

Optional parameters: None

Response: message [string] - ‘File deleted.’

Authentication

Protected resources, i.e. those requiring a user to log in, can be accessed via the API using OAuth (1.0A) authentication (see IETF RFC5849 for details). Third-party client software has to be registered with the BIGSdb site before they can access authenticated resources. The overall three-legged flow works as follows:

  1. Developer signs up and gets a consumer key and consumer secret specific to their application.

  2. Application gets a request token and directs user to authorization page on BIGSdb.

  3. BIGSdb asks user for authorization for application to access specific resource using their credentials. A verifier code is provided.

  4. The application exchanges the request token and OAuth verifier code for an access token and secret (these do not expire but may be revoked by the user or site admin).

  5. Application uses access token/secret to request session token (this is valid for 12 hours).

  6. All calls to access protected resources are signed using the session token/secret and consumer key/secret.

It is recommended that application developers use an OAuth library to generate and sign requests.

Note

There are Python and Perl example scripts available at https://github.com/kjolley/BIGSdb/tree/develop/scripts/rest_examples to demonstrate and test OAuth authentication.

Developer sign up to get a consumer key

Application developers should apply to the site administrator of the site running BIGSdb. The administrator can generate a key and secret using a script - both of these will need to be used by the application to sign requests.

The client id is usually a 24 character alphanumeric string. The secret is usually a 42 character alphanumeric (including punctuation) string, e.g.

  • client_id: efKXmqp2D0EBlMBkZaGC2lPf

  • client_secret: F$M+fQ2AFFB2YBDfF9fpHF^qSWJdmmN%L4Fxf5Gur3

Getting a request token

  • Relative URL: /db/{database}/oauth/get_request_token

  • Supported method: GET

The application uses the consumer key to obtain a request token. The request token is a temporary token used to initiate user authorization for the application and will expire in 60 minutes. The request needs to contain the following parameters and to be signed using the consumer secret:

  • oauth_consumer_key

  • oauth_request_method (‘GET’)

  • oauth_request_url (request URL)

  • oauth_signature_method (‘HMAC-SHA1’)

  • oauth_signature

  • oauth_timestamp (UNIX timestamp - seconds since Jan 1 1970) - this must be within 600 seconds of the current time.

  • oauth_callback (‘oob’ for desktop applications)

  • oauth_nonce (random string)

  • oauth_version (‘1.0’)

If the application has been registered and has been granted permission to access the specific resource, a JSON response will be returned containing the following parameters:

  • oauth_token

    • This is the request token. It is usually a 32 character alphanumeric string.

    • e.g. fKFm0WNhCfbEX8zQm6qhDA8K23FOWDGE

  • oauth_token_secret

    • This is the secret associated with the request token. It is usually a 32 character alphanumeric string.

    • e.g. aZ0fncP7i5w5jlebdK5zyQ4vrRRVcdnv

  • oauth_callback_confirmed

    • This parameter is always set to true.

Getting user authorization

Once a request token has been obtained, this can be used by the end user to grant permission to access a specific resource to the application. The application should direct the user to the client authorization page (authorizeClient) specific to a database within BIGSdb, e.g. http://pubmlst.org/cgi-bin/bigsdb/bigsdb.pl?db=pubmlst_neisseria_seqdef&page=authorizeClient&oauth_token=fKFm0WNhCfbEX8zQm6qhDA8K23FOWDGE

The user will be asked if they wish to grant access to the application on their behalf:

../_images/authorize_client.png

If they authorize the access, they will be presented with a verifier code. This should be entered in to the client application which will use this together with the request token to request an access token.

../_images/authorize_client2.png

The verifier code is valid for 60 minutes.

Getting an access token

  • Relative URL: /db/{database}/oauth/get_access_token

  • Supported method: GET

The application uses the request token, verifier code and its consumer key to obtain an access token. The access token does not expire but can be revoked by either the end user or the site administrator. The request needs to contain the following parameters and to be signed using the consumer secret and request token secret:

  • oauth_consumer_key

  • oauth_request_method (‘GET’)

  • oauth_request_url (request URL)

  • oauth_signature_method (‘HMAC-SHA1’)

  • oauth_signature

  • oauth_token (request token)

  • oauth_timestamp (UNIX timestamp - seconds since Jan 1 1970) - this must be within 600 seconds of the current time.

  • oauth_nonce (random string)

  • oauth_version (‘1.0’)

If the application has been registered and has been granted permission to access the specific resource, a JSON response will be returned containing the following parameters:

  • oauth_token

    • This is the access token. It is usually a 32 character alphanumeric string.

    • e.g. SDrC74ZVl5SYSqY8lWZqrRxnyDnNGVFO

  • oauth_token_secret

    • This is the secret associated with the access token. It is usually a 32 character alphanumeric string.

    • e.g. tYI2SPzgiO02IRVzW4JR1ez6Vvm4gVyv

Getting a session token

  • Relative URL: /db/{database}/oauth/get_session_token

  • Supported method: GET

The application uses the access token and its consumer key to obtain a session token. The session token is valid for 12 hours before it expires. The request needs to contain the following parameters and to be signed using the consumer secret and access token secret:

  • oauth_consumer_key

  • oauth_request_method (‘GET’)

  • oauth_request_url (request URL)

  • oauth_signature_method (‘HMAC-SHA1’)

  • oauth_signature

  • oauth_token (access token)

  • oauth_timestamp (UNIX timestamp - seconds since Jan 1 1970) - this must be within 600 seconds of the current time.

  • oauth_nonce (random string)

  • oauth_version (‘1.0’)

If the application has been registered and has been granted permission to access the specific resource, a JSON response will be returned containing the following parameters:

  • oauth_token

    • This is the session token. It is usually a 32 character alphanumeric string.

    • e.g. H8CjIS8Ikq6hwCUqUfF1l4pTaCYl8Ljw

  • oauth_token_secret

    • This is the secret associated with the session token. It is usually a 32 character alphanumeric string.

    • e.g. RfponbaNPO7tkZ2miHFISk0pMndePNfJ

Accessing protected resources

The application uses the session token and its consumer key to access a protected resource. The request needs to contain the following parameters and to be signed using the consumer secret and session token secret:

  • oauth_consumer_key

  • oauth_request_method (‘GET’)

  • oauth_request_url (request URL)

  • oauth_signature_method (‘HMAC-SHA1’)

  • oauth_signature

  • oauth_token (session token)

  • oauth_timestamp (UNIX timestamp - seconds since Jan 1 1970) - this must be within 600 seconds of the current time.

  • oauth_nonce (random string)

  • oauth_version (‘1.0’)