============ Generic info ============ .. warning:: This api is in development. Changes can and will be made without notice. API structure ============= The intemo sensor 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 ``/sensors//...`` example: ``https://josene.intemo.com/sensors/v1.2/devices`` 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: Bearer yEUqAXfH06WPr81IKU1X" "https://josene.intemo.com/sensors/v1.2/devices?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. .. _security-label: Security ======== Authentication and Authorization -------------------------------- API clients must authenticate themselves using an access token. You must pass an access token as an ``Authorization: Bearer`` HTTP header. This access token **must be kept secret**, it may **NOT** be used from client html or javascript that runs in a web browser or in an other device that is in control of an end-user. So the token may only be used for server to server communication. example: .. sourcecode:: http GET /sensors/v1.2/devices HTTP/1.1 Authorization: Bearer yEUqAXfH06WPr81IKU1X Accept-Encoding: gzip,deflate Host: josene.intemo.com .. COMMENTED OUT... pas as GET is not implemented For testing purposes, when trying out an API from your browser, you can also pass the access token as `GET` ``access_token`` parameter. example: .. sourcecode:: http GET /sensors/v1.2/devices?acces_token=yEUqAXfH06WPr81IKU1X HTTP/1.1 Accept-Encoding: gzip,deflate Host: hostname.com example curl request: .. sourcecode:: bash curl -H "Authorization: Bearer yEUqAXfH06WPr81IKU1X" https://josene.intemo.com/sensors/v1.2/devices .. note:: An token provides access to a single project. With that key you can access only sensors that belong to that particular project. If you need access to sensors of multiple projects, you will receive multiple api keys. Public Sensors -------------- A subset of the sensors are public (open for everybody). To access the public sensors you must use the public access token: ``zLimJQ09EZUzsH8kxzFk`` Inspect the API from your web browser ------------------------------------- If you are logged into the server, and you visit the api via a webbrowser you can inspect the requests and responses from your browser. Authentication is handled by your session cookie in that case. Ip Filtering ------------ The APIs are only available to whitelisten IP adresses (and IP ranges or country blocks). If you access an IP restricted api from an invalid IP. You get a 403 with an informative message. 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. .. COMMENTED OUT Rate limiting ============= .. TODO:: Document rate limiting References ========== This API is derived from the `Smart Emission Raw Sensor REST API `_.