.. _rest_api:

Rest Api
=============

Submit a job
------------

.. http:post:: /api/v1/job/submit

   Submit a job

   **Example request**:

   .. sourcecode:: javascript

    {
      'configuration' : {
        'profile': 'bacteria-gram+'
      }, 
      'sequence': 'MKKKQTTKALLVTCITDHKQDFYRLAFSYVKNQDDALDIVQESIKKALSSVETVRNPGTIKSWFYKILVRTAIDFLRKQKKIRVMDDETIEFLSKGKEDHYKDTDLHEALDELPYRYKTIIILRFFEDLKLEEIAEITGENTNTVKTRLYRALKLMRIQLTKEDLS'
    }

   **Example response**:

   .. sourcecode:: javascript

        {
          "id": "5be12dcd-f74f-41d0-9abd-41527553a13a",
          "created": "2019-05-14T13:58:18.892507Z",
          "lastUpdated": "2019-05-14T13:58:18.906208Z",
          "deleteAt": "2019-05-15T13:58:18.892507Z",
          "step": "fasta-validator",
          "request": {
            "type": "sequence",
            "configuration": {
              "profile": "bacteria-gram+"
            },
            "sequence": "FDSJKLFJDSFKLJDFHADJKLFHDSJKLFHDAFJKLDHFJKLDASFHDJKLFHDSAJKLFHDAKLFJDHSAFKLDLSNCDJKLFENFIUPERWDJKPCNVDFPIEHFDCFJDKOWFPDJWFKLXSJFDWFIPUAENDCXAMSFNDUAFIDJFDLKSAFJDSAKFLJDSADJFDWFIPUAENDCXAMSFNDAAAAAAAAAAAFJDSAKAA\n"
          },
          "files": [
            {
              "location": "input.fas",
              "name": "input.fas",
              "type": "Input"
            }
          ],
          "state": {
            "name": "waiting",
            "type": "Waiting"
          }
        }

   :<json sequence: The protein sequence, either raw or as fasta string
   :<json configuration.profile: The profile for the computation
   :<json source_app: An identifier of the app sends the request (optional)
   :statuscode 200: no error
   :statuscode 400: the request is invalid

Get job status
--------------

.. http:get:: /api/v1/job/(jobid)

   Get the job object

   **Example request**:

   **Example response**:

   .. sourcecode:: javascript

        {
          "id": "5be12dcd-f74f-41d0-9abd-41527553a13a",
          "created": "2019-05-14T13:58:18.892507Z",
          "lastUpdated": "2019-05-14T13:58:18.906208Z",
          "deleteAt": "2019-05-15T13:58:18.892507Z",
          "step": "fasta-validator",
          "request": {
            "type": "sequence",
            "configuration": {
              "profile": "bacteria-gram+"
            },
            "sequence": "FDSJKLFJDSFKLJDFHADJKLFHDSJKLFHDAFJKLDHFJKLDASFHDJKLFHDSAJKLFHDAKLFJDHSAFKLDLSNCDJKLFENFIUPERWDJKPCNVDFPIEHFDCFJDKOWFPDJWFKLXSJFDWFIPUAENDCXAMSFNDUAFIDJFDLKSAFJDSAKFLJDSADJFDWFIPUAENDCXAMSFNDAAAAAAAAAAAFJDSAKAA\n"
          },
          "files": [
            {
              "location": "input.fas",
              "name": "input.fas",
              "type": "Input"
            }
          ],
          "state": {
            "name": "waiting",
            "type": "Waiting"
          }
        }

   :param jobid: The job id
   :statuscode 200: no error
   :statuscode 404: the job does not exist

Delete a job
--------------

.. http:delete:: /api/v1/job/(jobid)

   Deletes the job

   **Example request**:

   **Example response**:

   :param jobid: The job id
   :statuscode 200: no error

Retrieve a job file
-------------------

.. http:get:: /api/v1/job/(jobid)/file/(filename)

   Get the job object

   **Example request**:

   **Example response**:

   .. sourcecode:: text

      >seq
      AAAA

   :param jobid: The job id
   :param filename: The filename
   :statuscode 200: no error
   :statuscode 404: the job or file does not exist


Access the eventbus
-------------------

.. http:get:: /api/v1/job/eventbus

   Join the eventbus. Use the appropriate vertx library to access the eventbus.


Resolve the representations of a dbxref
---------------------------------------

.. http:get:: /api/v1/dbxref/resolve/(dbxref)

   Get the locations where you can find representations of the dbxref.

   **Example request**:

   .. sourcecode:: http

      GET /api/v1/dbxref/retrieve/taxon:100 HTTP/1.1
      Host: psos-staging.computational.bio
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json
      
      [
        {"dbxref": "taxon:100", 
         "locations": {
           "html": ["http://www.uniprot.org/taxonomy/100"], 
           "json": ["https://www.ebi.ac.uk/ena/data/taxonomy/v1/taxon/tax-id/100"], 
           "xml": ["http://www.uniprot.org/taxonomy/100.rdf"], 
           "xml_ncbi": ["https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=taxonomy&id=100"]}, 
         "status": "found"}
      ]

   :param dbxref: The dbxref
   :statuscode 200: no error
   :statuscode 404: no information about the dbxref found

Retrieve a dbxref as json
-------------------------

.. http:get:: /api/v1/dbxref/retrieve/(dbxref)

   Retrieve a json representation of the dbxref.

   **Example request**:

   .. sourcecode:: http

      GET /api/v1/dbxref/retrieve/taxon:100 HTTP/1.1
      Host: psos-staging.computational.bio
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      [
        {
          "id": "Taxon:100", 
          "scientificName": "Ancylobacter aquaticus", 
          "lineage": ["Bacteria", "Proteobacteria", "Alphaproteobacteria", "Rhizobiales", "Xanthobacteraceae", "Ancylobacter"], 
          "rank": "species", 
          "geneticCodes": {
            "geneticCode": "11"
          }
        }
      ]

   :param dbxref: The dbxref
   :statuscode 200: no error
   :statuscode 404: no information about the dbxref found

Redirect to a html representation of a dbxref
----------------------------------------------

.. http:get:: /api/v1/dbxref/redirect/(dbxref)

   Redirect to a html representation of the dbxref.

   **Example request**:

   .. sourcecode:: http

      GET /api/v1/dbxref/redirect/taxon:100 HTTP/1.1
      Host: psos-staging.computational.bio
      Accept: application/json, text/javascript

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 303 See Other
      Location: http://www.uniprot.org/taxonomy/100

   :param dbxref: The dbxref
   :statuscode 303: no error, html representation found
   :statuscode 404: database in dbxref not supported