move domod and restd from deprecated to src/prog.

src/prog/restd/doc/source/understanding-the-api.rst

@@ -0,0 +1,106 @@
+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.
+