107 lines
4.9 KiB
ReStructuredText
107 lines
4.9 KiB
ReStructuredText
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.
|
|
|