API di integrazione

L’API di integrazione di Gridbeds permette a un’app di lavorare con le prenotazioni e gli ospiti dell’organizzazione che l’ha installata. Ogni pagina sotto Endpoint è generata dal documento OpenAPI dell’API, lo stesso file su cui l’API è costruita e verificata, e il suo playground invia richieste reali. Le pagine di riferimento sono in inglese, come il documento da cui sono generate. L’URL di base della produzione è https://api.gridbeds.com/api, e ogni percorso inizia con /v1/integration/. Il menu dei server del playground offre anche la sandbox.

Autenticazione

Invia un token di integrazione con ogni richiesta:

Authorization: Bearer <token>

Un token appartiene a una sola installazione di un’app. Chi nella struttura può gestire le integrazioni connette l’app in Gridbeds, da Impostazioni → Integrazioni (Marketplace app), e lì rilascia il token, concedendo i permessi (scope) richiesti dall’app o solo una parte. Il token viene mostrato una volta sola; rilasciarne uno nuovo revoca il precedente. Ogni operazione indica il permesso che richiede:

Permesso	Operazioni
nessuno	Get the calling installation
`reservations.read`	List reservations, Get a reservation
`reservations.write`	Create a reservation
`guests.read`	List guests
`guests.write`	Create a guest

Inizia da Get the calling installation: risponde con l’installazione, la sua organizzazione, il suo stato, l’app e i permessi concessi al token, e non richiede alcun permesso.

Un’organizzazione per token

Ogni richiesta legge e scrive i dati dell’organizzazione che ha installato l’app, e nient’altro. Un record di un’altra organizzazione risponde 404, esattamente come uno che non esiste.

Errori

Una richiesta rifiutata risponde con un corpo JSON:

Campo
`message`	Cosa non è andato, in una frase per una persona. Non basarti su di essa: il testo può cambiare e segue la lingua della richiesta.
`code`	Un identificativo stabile del rifiuto, presente quando c’è, per esempio `idempotency_key_reused`. Basati su questo.
`errors`	In caso di validazione non superata: i messaggi per ogni campo non valido, per nome del campo.

Stato	Quando
401	Il token manca, è sconosciuto o revocato, oppure è il token di accesso di un utente.
403	Al token non è stato concesso il permesso dell’operazione, oppure la sua installazione è disattivata o in errore.
404	Non c’è un record simile nell’organizzazione del token.
409	La prima richiesta con questo `Idempotency-Key` è ancora in elaborazione (`idempotency_in_flight`). Riprova tra poco.
422	La richiesta non ha superato la validazione, oppure chiede qualcosa che l’organizzazione non può fare (`code` dice cosa).
429	L’installazione ha superato il limite di richieste.

Limite di richieste

Un’installazione può fare 120 richieste al minuto. Oltre, l’API risponde 429 con l’header Retry-After, i secondi da attendere, insieme a X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (quando finisce la finestra, come timestamp Unix). Il corpo contiene error, message e retry_after.

Ripetere una creazione in sicurezza

Create a reservation e Create a guest accettano l’header Idempotency-Key. Per almeno 24 ore, la stessa chiave con lo stesso corpo risponde con la prima risposta invece di creare un secondo record. La stessa chiave con un corpo diverso viene rifiutata con 422 (idempotency_key_reused).

Versioni

La versione dell’API è nel percorso: /v1/. Il riferimento mostra la versione del documento OpenAPI; una modifica che romperebbe un client già costruito su di esso, come un’operazione o un campo di risposta rimosso o un campo di richiesta diventato obbligatorio, viene pubblicata solo come nuova versione maggiore del documento.

Identity

A chi appartiene il token: l’installazione, la sua organizzazione e i suoi permessi.

Reservations

Elenca, leggi e crea le prenotazioni dell’organizzazione.

Guests

Elenca e crea i profili degli ospiti per cui si fa una prenotazione.

​Autenticazione

​Un’organizzazione per token

​Errori

​Limite di richieste

​Ripetere una creazione in sicurezza

​Versioni