# Cloud API

Le API Cloud di Trackle sono di tipo [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). REST significa che usiamo l'URL nel modo per cui è stato creato ovvero come "Uniform Resource Locator". 

La risorsa in questione è il **Dispositivo**. Ogni dispositivo diventa un endpoint, che può essere usato per fare una richiesta `GET` e ottenere un valore, o una `POST` per chiamare una funzione remota o una `PUT` per aggiornare il firmware. 

Tutte le richieste ai dispositivi passano attraverso il nostro API Gateway con sicurezza **TLS**.

```bash
INDIRIZZO E PROTOCOLLO
"https://api.trackle.io"
```

{% hint style="info" %}
Quando scriviamo un nome preceduto da `:`, quel nome deve essere sostituito con un informazione di tua proprietà. Per esempio quando trovi un URL come `/v1/devices/:deviceId` devi sostituirlo con qualcosa tipo `/v1/devices/e00fce68166c3bbe15df4c6b`
{% endhint %}

## Formato

Le API REST accettano richieste in [JSON](https://www.w3schools.com/js/js_json_intro.asp) (content type `application/json`) e in [form encoded format](https://en.wikipedia.org/wiki/POST_\(HTTP%29) (content type `application/x-www-form-urlencoded`). Rispondono sempre con un JSON (content type `application/json`).

```aspnet
# Esempio in form encoded format
curl https://api.trackle.io/v1/devices/e00fce68166c3bbe15df4c6b/action \
     -d args=open \
     -d access_token=...

# Esempio con JSON
curl "https://api.trackle.io/v1/devices/e00fce68166c3bbe15df4c6b/action?access_token=..." \
     -H "Content-Type: application/json" \
     -d "{\"args\": \"open\"}"
```

In questa documentazione trovi esempi di chiamate alle API utilizzando un programma da terminale chiamato [curl](https://curl.haxx.se/) che dovrebbe essere già installato sul tuo PC.

Gli esempi usano *form encoded data* cosi da essere più semplici da leggere e da capire ma tutti gli endpoint accettano anche oggetti JSON come parametri.

## Errori

Le API Cloud di Trackle usano i codici di risposta HTTP convenzionali per indicare il successo o il fallimento di una richiesta alle API.  In generale: i codici `2xx` indicano successo. I codici `4xx`indicano un errore che riguarda le informazioni fornite (es., un parametro richiesto è stato omesso, etc.).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trackle.io/trackle-cloud/cloud-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.