============
Generic info
============

.. warning:: This api is in development. Changes can and will be made without notice.


API structure
=============


The Intemo cityzenz interface is a json REST api.

The API's are implemented in a way that you can inspect and test the API from your browser.

Their base url structure is ``/api/<version>/...``

example: ``/api/1.0/iot``


Content negotiation
-------------------

Content returned by de API is json only.

pretty output
.............

By default the json output is compact, if you pass the GET parameter pretty=true to a request, the json output is
pretty formatted. This can be useful when manually inspecting output via a web browser.

example curl request with pretty printing:


.. sourcecode:: bash

    curl -H "Authorization: Basic dXNlcjpzZWNyZXQ=" "https://sgauth.intemo.com/api/1.0./iot/ek-init?pretty=true"



POST Content Type
-----------------

when you POST/PUT/PATCH data you should pass one of the following content types

 * ``Content-Type: application/json``
 * ``Content-Type: application/vnd.api+json``

These are handled identical

HTTP compression
----------------
The API supports compressed responses. This is useful in case you are accessing API over the internet especially when you are issuing calls with potential large responses. By using http header compression you can reduce both bandwidth and delay.

Use ``Accept-Encoding: gzip`` as http header in your request to enable HTTP compression in the response.

example:
    .. sourcecode:: http

        GET /api/1.0/id HTTP/1.1
        Accept-Encoding: gzip,deflate
        Host: sandgrain.intemo.com


.. _security-label:

Security
========

Authentication and Authorization
--------------------------------

API clients must authenticate themselves using HTTP Basic auth when using the iot/ api.

1. HTTP Basic auth. See  :ref:`basic`


.. _basic:

Basic Auth
----------
example request for username = `user` and password = `secret`:

    .. sourcecode:: http

        POST /api/1.0/iot/ek-init HTTP/1.1
        Authorization: Basic dXNlcjpzZWNyZXQ=
        Host: sandgrain.intemo.com


Devices that use iot/ek-init api, must use http basic authentication

Devices that use the iot/meta api, must use an additional Bearer token.


Confidentiality
---------------
To ensure confidentiality of both the credentials as the data that passes the API, all access to the APIs is secured using HTTPS.

The API endpoints have valid, signed certificates. Your API client should check the validity of the certificates.