# ALTER API

The ALTER API allows programmers to access ALTER's functionality in a programmatic way, through a RESTful Web Service. Using this service, the server can be accessed from multiple programming languages, allowing researchers to wire ALTER results to their experiments. At this time, the API offers an unique convert function with multiple parameters plus some reflexible functions to retrieve the input/output program and formats currently supported.

Like any RESTful Web Service, operations are performed via web queries with a well-defined URL structure. The server API is located at %%HOST%%/api/

## Convert function

This function gives access to the ALTER's main functionality. It can be accessed through a POST request to:
%%HOST%%/api/convert
POST requests to servers can be performed in two ways (examples can be found below):

1. In a classic way, that is, via a web browser and a HTML page including a form. This is useful if you want to include the ALTER functionality in your webpage.
2. With any programming language acting as a 'fake' web browser (this is often done with a http helper library, available in many languages like perl (LWP), python (standard library), Java (Apache http-client), etc.). This is useful to call ALTER's functionality inside your own bioinformatics workflow

Both parameters and the input sequence are specified in this POST request. Here you can find which parameters are available and how to pass them to our server in our examples.

PARAMETER | DESCRIPTION
--- | ---
autodetect | Autodetect input so/program/format
inO | Input operating system
inP | Input program
inF | Input format
outO | Output operating system
outP | Output program
outF | output format
sequential (true|false) | Output in sequential form (ex: NEXUS, PHYLIP)
match (true|false) | Replace each character with '.' if it matches with the one at the place in first input sequence
lowercase (true|false) | Output sequences in lower case
resNumbers (true|false) | Output residue numbers (only in ALN format)
collapse (true|false) | Enable haplotype collapsing
gapsAsMissing (true|false) | Treat gaps as missing data in haplotype collapsing
countMissing (true|false) | Count missing data as differences when calculating sequence similarity on haplotype collapsing
limit | Collapse sequences whose differences are less than this value

### Client examples

You can use a web form or any programming environment able to perform HTTP Post requests.

#### Web form

You can find an example form here: %%HOST%%/api/form

#### Python

    # -*- coding: utf-8 -*-
    import httplib, urllib

    # input sequence
    sequence='''
    #NEXUS
    BEGIN DATA;
    dimensions ntax=4 nchar=673;
    format missing=?
    symbols="ABCDEFGHIKLMNOPQRSTUVWXYZ"
    interleave datatype=PROTEIN gap= -;

    matrix
    M17718      ---------------------------MESGNVSSSLFGNVSTALRPEAR
    X65879      ---------------------------MEYHNVSS-VLGNVSSVLRPDAR
    M17730      ---------------------------MEPLCNAS------EPPLRPEAR
    X65880      ---------------------------MDALCNAS------EPPLRPEAR

    M17718      LSAET---RLLGWNVPPEELRHIPEHWL----------TYPEPPESMNYL
    X65879      LSAES---RLLGWNVPPDELRHIPEHWL----------IYPEPPESMNYL
    M17730      -SSGNGDLQFLGWNVPPDQIQYIPEHWL----------TQLEPPASMHYM
    X65880      MSSGSDELQFLGWNVPPDQIQYIPEHWL----------TQLEPPASMHYM

    M17718      LG------------------------TLYIFFTLMSMLGNGLVIWVFSAA
    X65879      LG------------------------TLYIFFTVISMIGNGLVMWVFSAA
    M17730      LG------------------------VFYIFLFCASTVGNGMVIWIFSTS
    X65880      LG------------------------VFYIFLFFASTLGNGMVIWIFSTS

    M17718      KSLRTPSNILVINLAFCDFMMMVKTPIFIYNSFHQGYA--LGHLGCQIFG
    X65879      KSLRTPSNILVINLAFCDFMMMIKTPIFIYNSFHQGYA--LGHLGCQIFG
    M17730      KSLRTPSNMFVLNLAVFDLIMCLKAP--IFNSFHRGFAIYLGNTWCQIFA
    X65880      KSLRTPSNMFVLNLAVFDLIMCLKAPIFIYNSFHRGFA--LGNTWCQIFA

    M17718      IIGSYTGIAAGATNAFIAYDRFNVITRPMEG--KMTHGKAIAMIIFIYMY
    X65879      VIGSYTGIAAGATNAFIAYDRYNVITRPMEG--KMTHGKAIAMIIFIYLY
    M17730      SIGSYSGIGAGMTNAAIGYDRYNVITKPMNR--NMTFTKAVIMNIIIWLY
    X65880      SIGSYSGIGAGMTNAAIGYDRYNVITKPMNR--NMTFTKAVIMNIIIWLY

    M17718      ATPWVVACYTETWGRFVPEGYLTSCTFDYLT--DNFDTRLFVACIFFFSF
    X65879      ATPWVVACYTESWGRFVPEGYLTSCTFDYLT--DNFDTRLFVACIFFFSF
    M17730      CTPWVVLPLTQFWDRFVPEGYLTSCSFDYLS--DNFDTRLFVGTIFFFSF
    X65880      CTPWVVLPLTQFWDRFVPEGYLTSCSFDYLS--DNFDTRLFVGTIFLFSF

    M17718      VCPTTMITYYYSQIVGHVF---------------SHEKALRDQAKKMNVE
    X65879      VCPTTMITYYYSQIVGHVF---------------SHEKALRDQAKKMNVD
    M17730      VCPTLMILYYYSQIVGHVF---------------SHEKALREQAKKMNVE
    X65880      VVPTLMILYYYSQIVGHVF---------------NHEKALREQAKKMNVE

    M17718      SLRSNVDKNKE---------------------------------------
    X65879      SLRSNVDKSKE---------------------------------------
    M17730      SLRSNVDKSKE---------------------------------------
    X65880      SLRSNVDKSKE---------------------------------------

    M17718      --------------------------------------------------
    X65879      --------------------------------------------------
    M17730      --------------------------------------------------
    X65880      --------------------------------------------------

    M17718      ------------TAEIRIAKAAITICFLFFCSWTPYGVMSLIGAFGDKTL
    X65879      ------------AAEIRIAKAAITICFLFFASWTPYGVMSLIGAFGDKTL
    M17730      ------------TAEIRIAKAAITICFLFFVSWTPYGVMSLIGAFGDKSL
    X65880      ------------TAEIRIAKAAITICFLFFVSWTPYGVMSLIGAFGDKSL

    M17718      ---LTPGATMIPACACKMVACIDPFVYAISHPRYRMELQKRCPWLALNEK
    X65879      ---LTPGATMIPACTCKMVACIDPFVYAISHPRYRMELQKRCPWLAISEK
    M17730      ---LTQGATMIPACTCKLVACIDPFVYAISHPRYRLELQKRCPWLGVNEK
    X65880      ---LTPGATMIPACTCKLVACIEPFVYAISHPRYRMELQKRCPWLGVNEK

    M17718      APE--SSAVASTSTTQEPQQTTAA--------------------------
    X65879      APE--SRAAISTSTTQEQQQTTAA--------------------------
    M17730      SGE--ISSAQSTTTQEQ-QQTTAA--------------------------
    X65880      SGE--ASSAQSTTTQEQTQQTSAA--------------------------

    M17718      --------------------------------------------------
    X65879      --------------------------------------------------
    M17730      --------------------------------------------------
    X65880      --------------------------------------------------

    M17718      -----------------------
    X65879      -----------------------
    M17730      -----------------------
    X65880      -----------------------
    ;
    end;
    '''
    # conversion parameters (NOTE: these are not all possible parameters. Please see
    # the convert documentation, or take a look to the response, where all input parameters
    # are reported (including those that were not present in the request)
    params = urllib.urlencode({
      'autodetect': 'false',
      'inO': 'windows',
      'inP': 'clustal',
      'inF': 'NEXUS',
      'gapsAsMissing': 'true',
      'limit':0,
      'outF':'aln',
      'outO':'windows',
      'outP':'general',
      'sequence':sequence})

    # Make the request
    headers = {"Content-type": "application/x-www-form-urlencoded","Accept": "text/plain"}
    conn = httplib.HTTPConnection("sing.ei.uvigo.es")
    conn.request("POST", "/ALTER/api/convert", params, headers)
    response = conn.getresponse()
    data = response.read()

    # print the data
    print data
    conn.close()

#### Perl

    use strict;
    use warnings;
    use LWP 5.64;

    my $sequence = <<END;
    #NEXUS
    BEGIN DATA;
    dimensions ntax=4 nchar=673;
    format missing=?
    symbols="ABCDEFGHIKLMNOPQRSTUVWXYZ"
    interleave datatype=PROTEIN gap= -;

    matrix
    M17718      ---------------------------MESGNVSSSLFGNVSTALRPEAR
    X65879      ---------------------------MEYHNVSS-VLGNVSSVLRPDAR
    M17730      ---------------------------MEPLCNAS------EPPLRPEAR
    X65880      ---------------------------MDALCNAS------EPPLRPEAR

    M17718      LSAET---RLLGWNVPPEELRHIPEHWL----------TYPEPPESMNYL
    X65879      LSAES---RLLGWNVPPDELRHIPEHWL----------IYPEPPESMNYL
    M17730      -SSGNGDLQFLGWNVPPDQIQYIPEHWL----------TQLEPPASMHYM
    X65880      MSSGSDELQFLGWNVPPDQIQYIPEHWL----------TQLEPPASMHYM

    M17718      LG------------------------TLYIFFTLMSMLGNGLVIWVFSAA
    X65879      LG------------------------TLYIFFTVISMIGNGLVMWVFSAA
    M17730      LG------------------------VFYIFLFCASTVGNGMVIWIFSTS
    X65880      LG------------------------VFYIFLFFASTLGNGMVIWIFSTS

    M17718      KSLRTPSNILVINLAFCDFMMMVKTPIFIYNSFHQGYA--LGHLGCQIFG
    X65879      KSLRTPSNILVINLAFCDFMMMIKTPIFIYNSFHQGYA--LGHLGCQIFG
    M17730      KSLRTPSNMFVLNLAVFDLIMCLKAP--IFNSFHRGFAIYLGNTWCQIFA
    X65880      KSLRTPSNMFVLNLAVFDLIMCLKAPIFIYNSFHRGFA--LGNTWCQIFA

    M17718      IIGSYTGIAAGATNAFIAYDRFNVITRPMEG--KMTHGKAIAMIIFIYMY
    X65879      VIGSYTGIAAGATNAFIAYDRYNVITRPMEG--KMTHGKAIAMIIFIYLY
    M17730      SIGSYSGIGAGMTNAAIGYDRYNVITKPMNR--NMTFTKAVIMNIIIWLY
    X65880      SIGSYSGIGAGMTNAAIGYDRYNVITKPMNR--NMTFTKAVIMNIIIWLY

    M17718      ATPWVVACYTETWGRFVPEGYLTSCTFDYLT--DNFDTRLFVACIFFFSF
    X65879      ATPWVVACYTESWGRFVPEGYLTSCTFDYLT--DNFDTRLFVACIFFFSF
    M17730      CTPWVVLPLTQFWDRFVPEGYLTSCSFDYLS--DNFDTRLFVGTIFFFSF
    X65880      CTPWVVLPLTQFWDRFVPEGYLTSCSFDYLS--DNFDTRLFVGTIFLFSF

    M17718      VCPTTMITYYYSQIVGHVF---------------SHEKALRDQAKKMNVE
    X65879      VCPTTMITYYYSQIVGHVF---------------SHEKALRDQAKKMNVD
    M17730      VCPTLMILYYYSQIVGHVF---------------SHEKALREQAKKMNVE
    X65880      VVPTLMILYYYSQIVGHVF---------------NHEKALREQAKKMNVE

    M17718      SLRSNVDKNKE---------------------------------------
    X65879      SLRSNVDKSKE---------------------------------------
    M17730      SLRSNVDKSKE---------------------------------------
    X65880      SLRSNVDKSKE---------------------------------------

    M17718      --------------------------------------------------
    X65879      --------------------------------------------------
    M17730      --------------------------------------------------
    X65880      --------------------------------------------------

    M17718      ------------TAEIRIAKAAITICFLFFCSWTPYGVMSLIGAFGDKTL
    X65879      ------------AAEIRIAKAAITICFLFFASWTPYGVMSLIGAFGDKTL
    M17730      ------------TAEIRIAKAAITICFLFFVSWTPYGVMSLIGAFGDKSL
    X65880      ------------TAEIRIAKAAITICFLFFVSWTPYGVMSLIGAFGDKSL

    M17718      ---LTPGATMIPACACKMVACIDPFVYAISHPRYRMELQKRCPWLALNEK
    X65879      ---LTPGATMIPACTCKMVACIDPFVYAISHPRYRMELQKRCPWLAISEK
    M17730      ---LTQGATMIPACTCKLVACIDPFVYAISHPRYRLELQKRCPWLGVNEK
    X65880      ---LTPGATMIPACTCKLVACIEPFVYAISHPRYRMELQKRCPWLGVNEK

    M17718      APE--SSAVASTSTTQEPQQTTAA--------------------------
    X65879      APE--SRAAISTSTTQEQQQTTAA--------------------------
    M17730      SGE--ISSAQSTTTQEQ-QQTTAA--------------------------
    X65880      SGE--ASSAQSTTTQEQTQQTSAA--------------------------

    M17718      --------------------------------------------------
    X65879      --------------------------------------------------
    M17730      --------------------------------------------------
    X65880      --------------------------------------------------

    M17718      -----------------------
    X65879      -----------------------
    M17730      -----------------------
    X65880      -----------------------
    ;
    end;
    END

    my $browser = LWP::UserAgent->new;
    my $url = 'http://sing.ei.uvigo.es/ALTER/api/convert';

    # Request. (NOTE: these are not all possible parameters. Please see
    # the convert documentation, or take a look to the response, where all input parameters
    # are reported (including those that were not present in the request)
    my $response = $browser->post( $url,
        [ 'autodetect'=> 'false',
          'inO'=> 'windows',
          'inP'=> 'clustal',
          'inF'=> 'NEXUS',
          'gapsAsMissing'=> 'true',
          'limit'=>0,
          'outF'=>'aln',
          'outO'=>'windows',
          'outP'=>'general',
          'sequence'=>$sequence
        ]
      );

    die "$url error: ", $response->status_line unless $response->is_success;
    die "Weird content type at $url -- ", $response->content_type unless $response->content_type eq 'text/plain';

    print $response->content

## ALTER Reflective API

This set of functions gives access to the up-to-date supported input/output programs and formats, the available options per ouput program/format and the supported operating system.

- List the available operating systems to read files from.
  %%HOST%%/api/so
- List the supported input programs.
  %%HOST%%/api/input/programs
- List the supported input formats.
  %%HOST%%/api/input/formats
- List the supported output programs.
  %%HOST%%/api/output/programs
- List the supported output formats.
  %%HOST%%/api/output/formats
- List the supported output formats for a given output program.
  The structure of the URL is: %%HOST%%/api/output/{program}/formats
  Example: %%HOST%%/api/output/paml/formats
- List the supported options for a given output program and format.
  The structure of the URL is: %%HOST%%/api/output/{program}/{format}/options
  Example: %%HOST%%/api/output/paml/nexus/options