# Documentation API Yoplanning

### introduzione

L'API Yoplanning è strutturata attorno al principio REST. La nostra API fornisce URL prevedibili orientati alle risorse e utilizza codici di risposta HTTP per indicare errori e successo delle chiamate API. Sfruttiamo le funzionalità HTTP integrate, come l'autenticazione HTTP e i verbi HTTP, che sono compresi dai client HTTP standard. Tutti i metodi nella nostra API restituiscono JSON.

### Autenticazione

Per iniziare, devi richiedere un token API per poter interrogare l'API Yoplanning. Per fare questo, ti preghiamo di contattarci. Una volta che hai il token in mano, puoi iniziare a lavorare con l'API. Tutti i metodi API richiedono l'autenticazione.

Utilizziamo un sistema di autenticazione standard basato su token. Per autenticarti, fornisci semplicemente il tuo token API nell'intestazione di ciascuna richiesta come segue: `Autorizzazione: Token 4804c2cb4d87a13146d4de029f407c82149f2ada`. Attenzione: lo spazio tra "Token" e il token è importante.

Ecco un esempio completo utilizzando curl:

```
curl -H "Content-Type: application/json" https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients/8d23503e-041e-4180-98d1-641183bc5ead -H 'Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada'
```

Se non fornisci un token o il token non è valido, l'API risponderà con un codice HTTP 401 (non autorizzato) e ti fornirà un campo "dettagli" nel JSON di risposta per aiutarti a comprendere il problema.

### Autorizzazioni

Quando hai richiesto il tuo token API, ti sono state concesse autorizzazioni specifiche su un determinato insieme di team. Ciò significa che probabilmente non puoi utilizzare tutti i metodi nell'API. Se chiami l'API Yoplanning senza autorizzazioni, l'API risponderà con un codice HTTP 403 (Forbidden).

### Limitare le query

Per motivi di sicurezza il numero di richieste che puoi effettuare è limitato. Puoi inviare fino a 5 richieste al secondo e 1000 richieste al giorno. Oltre questa velocità, il server risponderà con un codice HTTP 429 (Troppe richieste).

### Panoramica

#### Squadra

Il team è il concetto fondamentale in Yoplanning (che è uno strumento collaborativo). Quasi tutti i metodi accettano un parametro teamId nell'URL, il che significa che tutte le azioni sono relative a un Team.

#### UUID

Molti metodi richiedono un parametro "pk" nell'URL. Questo è l'identificatore univoco della risorsa che stai tentando di recuperare/creare/aggiornare/eliminare. Yoplanning utilizza l'UUID (versione 4) come identificatore univoco per tutte le risorse.

#### Endpoint e verbi HTTP

Per molte risorse sono disponibili 2 endpoint:

* Uno per accedere a un'istanza specifica. L'URL solitamente termina con "".
* Uno per accedere al gestore dell'istanza: questi endpoint utilizzano i seguenti verbi HTTP:
  * GET: ottiene un elenco di tutte le risorse (vedi Paginazione)
  * POST: crea una nuova risorsa (l'identificatore verrà generato dal server)

#### Cercapersone

Per tutti i metodi API che forniscono un ampio elenco di risorse, viene utilizzata la paginazione. Ciò significa che non tutti i risultati verranno forniti in un'unica query. Sarà necessario eseguire più query per ottenere l'elenco completo delle risorse.

#### Filtri

Per alcuni endpoint è possibile filtrare i risultati aggiungendo parametri di query alla richiesta.

#### Campi espandibili

Per alcuni endpoint, l'oggetto risorsa contiene risorse nidificate. Per evitare di inviare più richieste è possibile utilizzare il meccanismo dell'estensione