Supporto e completezza dei dati

L'avvertenza sulla completezza, detta chiaramente

L'API Partner espone i record acquisiti dopo che la funzionalità è stata attivata per quel ristorante, in ogni collezione. Non pretende di contenere lo storico completo di un ristorante, e non lo recupererà a posteriori. Le consegne sono l'unica eccezione: le loro due collezioni riportano lo storico che l'app conservava ancora quando sono state aperte.

Questo conta più di quanto sembri:

• Un risultato vuoto non è la prova che non sia successo nulla. Può significare che il ristorante non era ancora attivato, oppure che un dispositivo non ha ancora caricato i dati.
• Un conteggio ottenuto da questa API non è un dato di conformità. Non lo stampi su un report che si legge come un audit.
• Se ha bisogno di conoscere la data di attivazione di un ristorante, lo chieda a noi o al cliente. Al momento non è esposta attraverso l'API. Se le serve come campo, ce lo dica e lo diventerà.

Le collezioni lo dicono nella loro stessa risposta: stateKind vale received-shadow-snapshot, cioè lo stato che questa API ha ricevuto, non lo stato che l'app del ristorante possiede. I due coincidono nel caso ordinario e divergono esattamente quando un dispositivo non ha ancora caricato i dati.

Una volta che un ristorante è attivato, i record arrivano in modo affidabile, compresi quelli acquisiti mentre un dispositivo era offline: vengono caricati quando si riconnette, ed è per questo che il polling incrementale dovrebbe sovrapporsi e per cui capturedAt e receivedAt sono entrambi su ogni record.

Versionamento

Ogni percorso ha il prefisso /v1, e questa API è in beta chiusa. Le chiavi vengono rilasciate a mano, a una manciata di integratori, e la forma dell'API non è ancora stabilita. Lo prenda alla lettera: all'interno di /v1, finché dura la beta, un endpoint può cambiare forma o essere ritirato, e non promettiamo il contrario.

Cosa significa in pratica:

• Sia tollerante nel parsing. Ignori i campi che non conosce anziché fallire su di essi; di campi se ne aggiungono spesso.
• Tenga d'occhio gli endpoint ritirati. Gli endpoint dedicati alle consegne, e lo scope che ne apriva le fotografie, non esistono più: le consegne si leggono come collezioni, come ogni altro tipo di record. Veda più sotto.
• Ci faccia sapere che esiste. Sappiamo quali chiavi ci hanno chiamato, e quando. Se la sua è in uso la contatteremo prima di spostare qualcosa sotto di essa, non perché la beta ci obblighi, ma perché rompere di sorpresa un'integrazione che funziona è un brutto modo di portarne avanti una.

Quando la beta finirà, questa sezione diventerà la promessa consueta: modifiche additive all'interno di una versione, tutto il resto dietro /v2. Non è ancora così, e dirlo le è più utile di una garanzia che dovremmo ritirare.

Il documento OpenAPI è generato dal servizio in esecuzione, quindi è la descrizione autorevole di ciò che è distribuito in questo momento. Se questa documentazione e quel documento non concordano, ha ragione il documento e noi abbiamo una pagina da correggere. Ce lo dica.

Controlli di stato

Due endpoint pubblici, senza autenticazione:

/health/ready è quello da interrogare se ci monitora. I controlli riusciti non vengono registrati nel log di audit, quindi un sistema di monitoraggio non aggiunge rumore.

Ottenere aiuto

Scriva a contact@backresto.com. Cosa rende rapida una risposta:

• il requestId del documento di problema, oppure l'X-Request-ID che ha inviato;
• il prefisso pubblico della sua chiave (la metà brp_… prima del punto, mai il secret);
• l'ambiente, l'endpoint e all'incirca quando.

Non ci mandi mai il secret di una chiave: il prefisso pubblico la identifica senza ambiguità. Se un secret è finito dove non doveva, lo dica nell'oggetto e ci invii il prefisso: la revoca è immediata, ed è tutto il rimedio. Veda Ottenere una chiave per il resto del ciclo di vita di una chiave.

Chiedere di più

Quello che esiste qui esiste perché qualcuno l'ha chiesto. Temperature di cottura e raffreddamento, piani di pulizia, etichette e un endpoint MCP ospitato erano tutti su questa lista qualche mese fa; adesso sono collezioni e un endpoint.

Le consegne erano l'ultima voce di questa lista. Sono state la prima cosa servita da questa API, attraverso endpoint propri, con una forma propria e un intervallo di tempo al posto di un cursore. Adesso sono due collezioni, deliveries e delivery-pictures, lette attraverso lo stesso involucro, la stessa paginazione e lo stesso GET .../collections/{collection}/records di ogni altro tipo di record, e i vecchi endpoint sono stati ritirati anziché mantenuti accanto. Un solo modo di leggere un record è il senso del cambiamento. Se ha costruito sui vecchi endpoint, Consegne mostra la nuova forma, e siamo felici di aiutarla nel passaggio.

Cosa c'è ancora in lista: i webhook al posto del polling, un cursore incrementale sulle collezioni, una data di attivazione sul ristorante, e l'accesso OAuth per i client MCP che non accettano una chiave. Quale arriva per primo lo decide chi lo chiede. Quindi lo chieda.