openstamanager/docs/API.md

140 lines
5.5 KiB
Markdown

---
currentMenu: api
---
# API
> Con application programming interface (in acronimo API, in italiano interfaccia di programmazione di un'applicazione), in informatica, si indica ogni insieme di procedure disponibili al programmatore, di solito raggruppate a formare un set di strumenti specifici per l'espletamento di un determinato compito all'interno di un certo programma.
>
> \-- <cite>[Wikipedia](https://it.wikipedia.org/wiki/Application_programming_interface)</cite>
L'API del progetto è attualmente ancora in sviluppo, e pertanto le funzioni disponibili potrebbero essere piuttosto ridotte.
Di seguito sono elencate le basi per connettersi al sistema e ottenere i dati a cui si è interessati.
<!-- TOC depthFrom:2 depthTo:6 orderedList:false updateOnSave:true withLinks:true -->
- [Standard di comunicazione](#standard-di-comunicazione)
- [Ottenere la chiave](#ottenere-la-chiave)
- [Formato dei componenti](#formato-dei-componenti)
- [Output](#output)
- [Stati](#stati)
- [Lettura](#lettura)
- [Personalizzazione](#personalizzazione)
- [Richieste di lettura](#richieste-di-lettura)
- [Interventi](#interventi)
- [Anagrafiche](#anagrafiche)
- [Richieste disabilitate](#richieste-disabilitate)
- [Modifiche](#modifiche)
- [Eliminazioni](#eliminazioni)
<!-- /TOC -->
## Standard di comunicazione
Il funzionamento dell'API si basa fondamentalmente sull'utilizzo di una chiave di accesso, ospitata all'interno della tabella `zz_tokens` del database del progetto, univoca per ogni istanza dell'utente.
Ogni richiesta all'API deve contenere la chiave di accesso (campo `token`) e l'operazione richiesta (campo `resource`), inserendo questi elementi tra gli ulteriori contenuti che si intendono inviare.
I contenuti della richiesta devono quindi essere convertiti in formato JSON ed inviati all'API secondo uno specifico schema:
- `POST` - Richieste di creazione (**Create**).
- `GET` - Richieste di informazioni (**Retrieve**).
- `PUT` - Richieste di modifica (**Update**).
- `DELETE` - Richieste di eliminazione (**Delete**).
### Ottenere la chiave
La chiave di accesso può essere ottenuta sfruttando l'operazione di accesso nativa dell'API, che prevede l'invio di una richiesta **POST** corrispondente alla seguente struttura:
- `resource` - login.
- `username` - &lt;username dell'account>.
- `password` - &lt;password dell'account>.
### Formato dei componenti
I seguenti componenti delle richieste devono seguire una rigida struttura:
- `page` - intero.
- `upd` - yyyy-MM-dd hh:mm:ss.
## Output
L'API del progetto permette di ottenere le informazioni attraverso un array in formato JSON.
### Stati
Ogni richiesta effettuata all'API viene accompagnata da un messaggio predefinito che permette di interpretare in modo più preciso la risposta.
In particolare, sono presenti i seguenti _status_:
- `200: OK` - La richiesta è andata a buon fine.
- `400: Errore interno dell'API` - La richiesta effettuata risulta invalida per l'API.
- `401: Non autorizzato` - Accesso non autorizzato.
- `404: Non trovato` - La risorsa richiesta non risulta disponibile.
- `500: Errore del server` - Il gestionale non è in grado di completare la richiesta.
- `503: Servizio non disponibile` - L'API del gestionale non è abilitata.
### Lettura
Le richieste di lettura sono solitamente completate con l'invio di un numero predefinito di informazioni.
Per poter interpretare correttamente i dati, si devono ignorare gli indici numerici di primo livello (non rilevanti all'interno del formato) e sfruttare in particolare i seguenti campi generici:
- `records`, rappresentante il numero totale dei record richiesti;
- `pages`, indicante il numero totale della pagine disponibili.
Si ricorda che l'API prevede la restituzione di un insieme di dati limitato rispetto alla richiesta effettuatua: per ottenere l'intero insieme di informazioni è necessario eseguire molteplici richieste consecutive basate sul campo `page`.
## Personalizzazione
L'API sfrutta una struttura modulare per poter funzionare in modo completo e garantire al tempo stesso il possibile ampliamento delle sue funzioni.
In particolare, ogni modulo può specificare una determinata serie di operazioni che lo riguardano e che possono essere richiamate in vari modi.
Di seguito lo schema attraverso cui l'API individua la presenza delle possibili richieste supportate dai moduli (cartelle **api/** e **custom/api/**):
- `POST` - File `create.php`.
- `GET` - File `retrieve.php`.
- `PUT` - File `update.php`.
- `DELETE` - File `delete.php`.
## Richieste di lettura
### Interventi
Tutto il contenuto della tabella in_interventi:
http://<url_osm>/api/?token=<token>&resource=in_interventi
Singolo intervento (riga della tabella):
http://<url_osm>/api/?token=<token>&resource=in_interventi&filter[id]=[1]
### Anagrafiche
Tutto il contenuto della tabella an_anagrafiche:
http://<url_osm>/api/?token=<token>&resource=an_anagrafiche
Singolo intervento (riga della tabella):
http://<url_osm>/api/?token=<token>&resource=an_anagrafiche&filter[idanagrafica]=[1]
Ricerca per ragione sociale:
http://<url_osm>/api/?token=<token>&resource=an_anagrafiche&filter[ragione_sociale]=[%<stringa_ragione_sociale>%]
### Richieste disabilitate
#### Modifiche
Tutti i contenuti di tutte le tabelle:
http://<url_osm>/api/?token=<token>&resource=updates
Tutti i contenuti di tutte le tabelle, aggiornati a partire da una data precisa:
http://<url_osm>/api/?token=<token>&resource=updates&upd=2016-01-31%2010:44:31
#### Eliminazioni
Tutte le eliminazioni di tutte le tabelle:
http://<url_osm>/api/?token=<token>&resource=deleted