APIS
====

.. note::

    To make development easier, we advise you to consider `requests <http://docs.python-requests.org/en/latest/>`_ 
    over `urlib` or any other `HTTP` library in Python.


Account Resource
----------------

.. http:get:: /private/account/signup

   Creates a new user on Aurum and other subsystems in Graphyte (GCS and Natrium).

   **Example request**:

   .. sourcecode:: http

      curl --data "username=<username>&password=<password>&masteru=<masteru>&masterp=<masterp>"
        https://example.com/aurum/private/account/signup -k

      POST /aurum/private/account/signup HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 201 OK
      Vary: Accept
      Content-Type: text/html; charset=UTF-8

      {
          "access_key": "82865e3f0df5fcc9748a3a354c220d7e",
          "status": "201",
          "reason": "User exampleuser created."
      }


   :queryparam username: username of the new account
   :queryparam password: password of the new account in plaintext
   :queryparam masteru: administrator username
   :queryparam masterp: administrator password in plaintext
   :statuscode 201: account created in all subsystems
   :statuscode 400: password is less than six characters
   :statuscode 409: username already exists in Aurum
   :statuscode 500: unknown internal service error


Exercise Resource
-----------------

.. http:post:: /api/exerise

   Creates a new exercise resource. 

   **Example request**:

   .. sourcecode:: http

      curl --data "username=<username>&password=<password>&repo=<repo_url>&exercise_id=<exercise_id>"
        https://example.com/aurum/api/exercise -k

      POST /aurum/api/exercise HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 201 OK
      Vary: Accept
      Content-Type: text/html; charset=UTF-8

      {
          "access_key": "19312b8a9cd49af331c8adc0d65ddfd1",
          "exercise_id": "61ee6bd343a3bb3f7215b8ef906d1c35"
      }
 
   :queryparam username: instructor username
   :queryparam password: instructor account password in plaintext
   :queryparam repo: full path to the repo (https://bitbucket.org/user1/repo1, ssh://hg@bitbucet.org/user1/repo1)
   :queryparam exercise_id: a predefined exercise-id (optional)
   :statuscode 201: (possibly new) exercise record is created
   :statuscode 400: user not found
   :statuscode 401: authentication failed