Understanding the API
=====================

How does it work ?
~~~~~~~~~~~~~~~~~~

In an effort to provide the end-user with the ability to efficiently control and customize his device, a *RESTful* HTTP based
API has been developped on the AwoX Audio Striim Device. It is hosted by a webserver which runs on the port ``34000`` and
accepts HTTP connections.

Our web service is built to address two important roles : first, he is binding a set of URLs to the right API routes responsible of
handling an action, such as a Wi-Fi connection request. Next, we use it as a static page provider in order to let the user access a 
full HTML/CSS configuration website. 
The configuration website is an independant application running on the user browser and acts as a client of the WAPI. This allows us
to both develop and test our API on one side, while integrating our web app on the other side. This also allows us to decouple the 
development of both of them which dramatically speeds up the development/testing part.

Talking to the API
~~~~~~~~~~~~~~~~~~

Handling CORS request
^^^^^^^^^^^^^^^^^^^^^

Interacting with an HTTP-based API from a native program or a smartphone app is usally not a big deal. However, interacting 
with it through AJAX Javascript calls can rapidly become a painful experience because of Cross-domain policies. To address 
this kind of issues, the server uses cross-domain resource sharing through the use of specific HTTP headers we are joining to
the response part :

.. code-block:: http

    Access-Control-Allow-Origin: *
    Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
    Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept


Response objects layout
^^^^^^^^^^^^^^^^^^^^^^^

The Rest Daemon could responde in XML or in JSon. the two kind of object is provided by the Rest Server.

Every response sent by the WAPI is serialized into an object similarly in XML or in JSon.

Each object that is returned has a specific layout associated to a specific type. Each returned object extends a base
object which contains three attributes that are sent with every response. This base object has the following representation:

For JSon

.. code-block:: json
        
    {
        "id": string,
        "status": string,
        "response_code": number
    }

For Xml

.. code-block:: xml
      
      
	<?xml version="1.0" encoding="ISO-8859-1" ?>
	<request id="XXXX">
	<Status></Status>
	...
	</request>
	

The ``id`` field correspond to the request ID we want to do.

The ``Status`` field could be ``passed`` or ``failed`` and correspond of the status of the request.

The ``response_code`` integer is also a representation of the response. In most cases, this code will be equal to the HTTP
response code sent with the response at HTTP level.

As said before, these fields are embedded in every responses sent by the API. One or more field can be added to the response
depending on the accessed route.
A list of all the existing JSON objects is documented in the :doc:`Models<api-models>` page. You can bind these models to your
actual class hierarchy in your code when deserializing the JSON/XML response.

Also note that the documentation about each routes will inform you about the potential object types that are expected in the
response.

Expected Response Objects
~~~~~~~~~~~~~~~~~~~~~~~~~

When issuing a request and receiving a response back, you should pay attention to two things : the HTTP response code, which
is always meaningful, and the JSON object sent in the response. The documentation related to each route provides a detailed
set of responses that should be expected by the client to receive. Nevertheless, you should not always expect the expectable
and be sure that your error handlers are correctly handling the following cases for every API call :

    - A ``404`` Object you try to access is not available. 
    - A ``405`` Method Not Allowed response will be issued if the HTTP method is wrong.    
    - A ``412`` Expectation Failed response will be issued if the parameters that are expected with the request are missing or considered invalid.
    - A ``500`` Internal Server Error response will be issued if a severe error happened server-side. A meaningful textual message can be available within the message attribute of the object to state what did happen.

    - You should be using a timeout on each of your request to advertise a user that something bad happened and that you cannot reach the remote device anymore if a timeout is triggered. A reasonnable value is expected on a LAN.


Properly encoding the request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We expect the characters you send us to be encoded in UTF-8. This should be pretty straightforward if you work on Android 
or iOS. We also need your parameters to be properly percent-encoded (also referred as URL encoding).

The strings wrapped in the response we will send you back will also be UTF-8 encoded and percent-encoded.

