Come funziona l'API di Optifora
Questa pagina descrive la forma dell'API: come si dimostra l'identità, come avanzano le versioni, entro quali limiti resta una richiesta, che aspetto ha un errore e come si scambiano i dati con l'esterno.
Il prodotto è in fase di sviluppo e la superficie dell'API è ancora in via di completamento. Un documento di riferimento per gli endpoint sarà pubblicato separatamente; questa pagina non riporta né indirizzi né chiamate di esempio, ma solo il funzionamento.
Autenticazione
Ogni richiesta appartiene a una persona oppure a un'applicazione registrata. Una richiesta priva di identità che raggiunge un endpoint protetto torna indietro come non autenticata.
- Token BearerIl token di accesso viaggia nell'intestazione di autorizzazione della richiesta. È firmato e dichiara soltanto a chi appartiene la richiesta.
- Vita breveUn token di accesso scade dopo un intervallo misurato in minuti; la durata è un parametro di installazione e vale trenta minuti per impostazione predefinita.
- Rinnovo e rotazioneUna sessione si prolunga con un token di rinnovo e ogni proroga emette una nuova coppia. Se un token di rinnovo già consumato viene presentato una seconda volta, tutte le sessioni di quella persona vengono revocate.
- I permessi non sono incorporati nel tokenIl token porta con sé solo l'identità; ciò che una persona può vedere viene chiesto al database a ogni richiesta. Un permesso ritirato smette quindi di funzionare prima che scada il token già in mano.
- Chiave dell'integratoreUn'applicazione registrata si collega con la propria chiave. Il valore in chiaro viene mostrato una sola volta, alla creazione; ciò che viene conservato è la sua impronta e il prefisso non segreto che consente di riconoscere la chiave.
- L'accesso lo concede l'organizzazionePer quanto diffusa sia un'applicazione, senza un'autorizzazione registrata dall'organizzazione non vede nemmeno una riga. L'autorizzazione è datata, delimitata e revocabile.
Versionamento
- La versione sta nel percorsoGli endpoint sono pubblicati dietro un prefisso di versione; la superficie odierna è la versione uno.
- Una modifica incompatibile apre un nuovo percorsoIl contratto di un endpoint esistente non viene infranto sul posto. Una modifica incompatibile viene pubblicata su un nuovo percorso di versione mentre il precedente continua a funzionare.
- Il documento dichiara la propria versioneIl riferimento riporta il numero di versione da cui è stato generato; quale versione state leggendo lo dice il documento stesso.
Ambienti e limiti
Il riferimento dichiara due ambienti: produzione e sviluppo locale. L'indirizzo radice viene consegnato all'integratore insieme alla sua chiave; non è pubblicato in questa pagina.
- Liveness e readiness si misurano separatamenteUn endpoint dichiara che il processo è attivo; il secondo invia una query reale al database e conferma che è raggiungibile. Solo il secondo decide se inviare traffico.
- Le origini del browser sono limitate a un elencoLe richieste cross-origin sono accettate solo dalle origini dichiarate in anticipo; finché l'elenco resta vuoto, una richiesta cross-origin dal browser viene rifiutata.
- Limite del corpoIl corpo di una richiesta non può superare i cinque megabyte. Gli insiemi di grandi dimensioni viaggiano come processo di trasferimento massivo con un proprio record di stato, non come richiesta unica.
- I segreti non vengono scritti nel logIl log del server non conserva intestazioni di autorizzazione, cookie, password né codici identificativi nazionali.
Limite di frequenza
Il limite è per indirizzo e per minuto. Il valore predefinito è di 120 richieste al minuto e si imposta in fase di installazione. La quota residua viene comunicata nelle intestazioni di ogni risposta.
| Intestazione della risposta | Che cosa indica |
|---|---|
| x-ratelimit-limit | La quota complessiva all'interno della finestra. |
| x-ratelimit-remaining | Quanto resta in questa finestra. |
| x-ratelimit-reset | Secondi mancanti al rinnovo della quota. |
| retry-after | Quanti secondi attendere prima di riprovare. Presente solo nella risposta che ha rifiutato la richiesta. |
Una volta superato il limite la richiesta viene rifiutata e la risposta indica, in secondi, quanto attendere. Il nuovo tentativo si fa dopo quel tempo, non subito.
Formato degli errori
Ogni errore torna nella stessa busta: un campo con un codice breve su cui la macchina si dirama e un campo di spiegazione che una persona può leggere.
- errorIl codice breve su cui decide il client.
- messageLa spiegazione di quanto è accaduto.
| Stato | Campo del codice | Che cosa significa |
|---|---|---|
| 400 | Bad Request | La richiesta non corrisponde allo schema. La spiegazione indica il campo mancante o non valido. |
| 401 | unauthenticated | Non c'è un'identità valida: nessun token è stato inviato, è scaduto oppure non è stato verificato. |
| 404 | Not Found | Endpoint inesistente, oppure record inesistente. |
| 429 | Too Many Requests | Il limite di frequenza è stato superato; la risposta indica quanto attendere. |
| 5xx | internal_error | Un guasto imprevisto. Il dettaglio non viene consegnato al client; viene scritto nel log del server. |
Paginazione
Gli endpoint che restituiscono elenchi accettano gli stessi due parametri e restituiscono gli stessi contatori, così un client di paginazione non va riscritto per ogni endpoint.
- limitQuanti record deve contenere una pagina. Almeno uno, al massimo duecento; cinquanta se non impostato.
- offsetQuanti record saltare. Parte da zero.
- totalQuanti record corrispondono in totale ai filtri.
- countQuanti record trasporta effettivamente questa risposta.
La risposta restituisce anche il limit e l'offset che ha utilizzato; il client legge la propria posizione dalla risposta invece di indovinarla.
Scambio dati e webhook
La modalità di scambio è un'impostazione, non un prodotto a parte: ogni applicazione registrata porta sul proprio record la modalità con cui lavora.
| Modalità | Che cosa significa |
|---|---|
| Unidirezionale — in uscita | Optifora pubblica i dati; l'altra parte li legge oppure si iscrive agli eventi. |
| Unidirezionale — in entrata | L'altra parte invia i dati; Optifora li convalida e li scrive. |
| Bidirezionale | Scrivono entrambe le parti; la regola di risoluzione dei conflitti è definita in anticipo. |
| Handshake | Ogni trasferimento apre una sessione: proposta, verifica, approvazione, trasferimento e ricevuta. La ricevuta resta a entrambe le parti. |
- Gli eventi vengono inviati all'esternoUn webhook invia l'evento all'indirizzo di callback dichiarato dall'applicazione registrata. Un evento che non può essere consegnato resta in coda e viene ritentato; non viene mai scartato in silenzio.
- La stessa richiesta non scrive due volteUna richiesta di scrittura porta con sé una chiave di idempotenza. Una seconda richiesta con la stessa chiave non crea un secondo record.
- Ogni chiamata viene misurataChi ha chiamato, quando, con quale ambito e con quale esito: tutto viene registrato. Lo stesso registro risponde sia al debug sia alla domanda su chi abbia estratto questi dati.
- Le nostre applicazioni usano la stessa portaNon esiste una seconda via privilegiata. La nostra stessa integrazione è la prova della superficie che incontra uno sviluppatore esterno.
Il modello dati del livello di scambio è pronto; i suoi endpoint non sono ancora pubblicati. Quando lo saranno, questa sezione rimanderà alle relative voci nel riferimento.
Documenti di riferimento
Il riferimento non è scritto a mano; è generato dagli schemi degli endpoint. Man mano che ogni endpoint consegna il proprio schema il documento si completa da sé, così documento e comportamento non possono divergere.
- Oggi: in preparazioneGli schemi avanzano modulo per modulo. Prima della pubblicazione del documento, la richiesta e la risposta di ogni endpoint saranno visibili al suo interno.
- Saranno pubblicati due formatiUn documento OpenAPI leggibile dalla macchina e una pagina di riferimento generata dallo stesso documento e consultabile nel browser.
- L'accesso è a livelliLa panoramica è aperta a chiunque. Il riferimento completo può restare dietro un token di documentazione consegnato a un integratore registrato; le chiavi di produzione e gli indirizzi di callback non sono affatto materia di documentazione: appartengono al record dell'applicazione.
- Standard degli indirizziVengono pubblicati due riferimenti e i loro indirizzi sono fissi: client-api.optifora.com/docs è aperto, admin-api.optifora.com/docs richiede autorizzazione ed è chiuso all'esterno. Nessuno dei due è attivo oggi; i collegamenti saranno aggiunti a questa sezione quando lo saranno.
Se il vostro progetto di integrazione è già definito, scriveteci dalla pagina dei contatti: sarete tra i primi a essere avvisati quando la superficie si aprirà.
Avete una richiesta specifica?
Queste pagine spiegano come funziona il processo di assistenza. Se avete una richiesta o una domanda, scriveteci dalla pagina dei contatti.
Vai alla pagina dei contatti