Quando si progetta e si realizza l'integrazione di un'API, è facile concentrarsi molto sui dettagli delle operazioni, degli attributi e dei parametri e dimenticare di considerare fattori che potrebbero avere un impatto significativo sulle prestazioni, sulla stabilità e sulla manutenzione dell'integrazione.
Dare a tali fattori l'attenzione che meritano può fare la differenza tra un'integrazione inaffidabile e una invece ben solida. Per assicurarti che la tua integrazione sia la migliore possibile, consigliamo vivamente di incorporare queste quattro best practice per le API di Smartsheet:
1. Essere efficiente: usare le operazioni abilitate in blocco
Per il massimo dell'efficienza, usa le operazioni dell'API abilitate in blocco, quando è possibile. Un'operazione dell'API abilitata in blocco ti consente di aggiungere, aggiornare o eliminare più elementi usando una singola richiesta API.
Per esempio, se devi aggiornare 10 righe all'interno di un foglio, puoi farlo usando una singola richiesta di aggiornamento righe, piuttosto che eseguire 10 richieste separate (una per ogni riga).
Le operazioni abilitate in blocco migliorano l'efficienza riducendo drasticamente il numero di chiamate in uscita che l'integrazione deve eseguire. Questo riduce le possibilità di raggiungere il limite di velocità (poiché ogni operazione in blocco conta come una sola richiesta al fine del calcolo del limite).
Le seguenti operazioni dell'API ti consentono attualmente di completare queste attività in blocco:
In futuro, aggiungeremo altre operazioni abilitate in blocco; non lasciarti sfuggire queste opportunità per migliorare l'efficienza. E ricorda, è una best practice fare le cose in blocco quando è possibile.
Consiglio: consenti il successo parziale
Generalmente, quando si genera un errore durante un'operazione in blocco, il comportamento predefinito è la mancata riuscita dell'intera operazione. Per esempio, se si effettua una richiesta di aggiornamento delle righe e uno degli oggetti riga nella richiesta non è valido, l'intera operazione avrà esito negativo e nessuna riga verrà aggiornata.
Tuttavia, esiste un'opzione che consente il successo parziale per le richieste in blocco. Consentendo il successo parziale, si consente l'esecuzione delle porzioni valide della richiesta anche se si generano errori durante l'operazione.
2. Essere pratici: aderire alle linee guida di limitazione della velocità
Gestire l'errore di raggiungimento del limite di velocità
L'API Smartsheet attualmente impone un limite di velocità di 300 richieste al minuto per token di accesso.
Alcune operazioni che richiedono numerose risorse, come allegare un file o ottenere la cronologia di una cella contano come 10 richieste al fine del calcolo del limite. Se si supera questo limite di velocità, le successive richieste dell'API (all'interno di un periodo di un minuto) presenteranno un errore di stato HTTP 429, insieme al seguente messaggio di risposta JSON:
{
“errorCode”: 4003,
“message”: “Rate limit exceeded.”
}
Consigliamo di progettare l'integrazione in modo che gestisca in modo normale questo errore del limite di velocità. Un modo per farlo, è mettere in sospensione l'integrazione per 60 secondi quando si incontra l'errore e quindi riprovare con la richiesta.
In alternativa, è possibile scegliere di implementare il backoff esponenziale, una strategia di gestione degli errori con la quale si riprova una richiesta con esito negativo con tempi di attesa progressivamente più lunghi tra i tentativi, fino alla riuscita della richiesta o fino a che si raggiunge un certo numero di tentativi.
Evita di eseguire aggiornamenti a "mitragliatrice"
Inoltre, sconsigliamo vivamente di eseguire le richieste dell'API in rapida successione per aggiornare uno specifico oggetto Smartsheet più e più volte in un brevissimo periodo di tempo.
Per esempio, se l'unica cosa che fa la tua integrazione è eseguire una richiesta di aggiornamento righe una volta al secondo per lo stesso foglio, questo ammonterà a un totale di sole 60 richieste al minuto, ben al di sotto del limite impostato.
Tuttavia, l'aggiornamento dello stesso oggetto in una successione così rapida potrebbe portare a errori di salvataggio che hanno un impatto negativo sia sull'integrazione sia sull'esperienza utente all'interno della piattaforma Smartsheet.
Per evitare questa situazione, progetta la tua integrazione in modo che le richieste dell'API non siano mai eseguite in successione rapida per lo stesso oggetto Smartsheet. Per il massimo dell'efficienza, prendi in considerazione il raggruppamento delle modifiche e il loro invio in un'unica richiesta attraverso un'operazione abilitata in blocco (per es. aggiornamento righe o aggiunta colonne).
Esegui le richieste in modo seriale
Consigliamo inoltre vivamente di non eseguire richieste dell'API multiple in parallelo per aggiornare uno specifico oggetto Smartsheet. In questo modo si ridurranno le prestazioni e, con tutta probabilità, si incorrerà in errori dovuti a collisioni dei salvataggi.
Per evitare questa situazione, progetta la tua integrazione in modo che le richieste dell'API per l'aggiornamento di uno specifico oggetto Smartsheet siano sempre eseguite in modo seriale, ovvero eseguendo una richiesta alla volta e non iniziando la richiesta successiva prima che la precedente sia stata completata.
3. Essere intelligenti: gestire gli errori adeguatamente
Una richiesta dell'API con esito positivo genera un codice di stato HTTP 200, insieme ai dati relativi all'operazione eseguita all'interno del corpo della risposta. Ma che cosa accade se qualcosa va storto e si riceve una risposta diversa da 200? La capacità di gestire gli errori adeguatamente è un componente critico di un'integrazione API di qualità.
Se una richiesta dell'API di Smartsheet ha esito negativo, l'API riporta un codice di stato HTTP 4xx o 5xx, insieme a un corpo della risposta JSON che specifica i dettagli dell'errore verificatosi. Per esempio, se si esegue una richiesta di ottenimento di un foglio usando un ID foglio non valido (inesistente), la risposta riporterà un codice di stato HTTP 404 con il seguente corpo della risposta JSON:
{
“errorCode”: 1006,
“message”: “Not Found”
}
Quando dovresti riprovare?
Una strategia di gestione degli errori di successo richiede che l'integrazione riconosca la differenza tra gli errori che possono potenzialmente essere risolti riprovando la richiesta e gli errori che non devono mai prevedere un nuovo tentativo automatico.
Il codice di stato HTTP visualizzato con una risposta è la prima indicazione del risultato della richiesta.
Consigli per la gestione degli errori
Oltre al codice di stato HTTP, devi valutare anche il codice di errore specifico di Smartsheet che viene visualizzato nel corpo della risposta per le richieste con esito negativo. Per esempio:
{
“errorCode”: 1006,
“message”: “Not Found”
}
La documentazione dell'API specifica le raccomandazioni per la gestione degli errori per ciascun codice di errore specifico di Smartsheet. Ti consigliamo di usare queste informazioni per implementare la logica della gestione degli errori secondo le linee guida seguenti:
-
Se il codice di errore indica una condizione di errore permanente, non riprovare con la richiesta.
-
Se il codice di errore indica un problema che può essere risolto, non riprovare con la richiesta fino a che il problema non è stato risolto.
-
Se il codice di errore indica un problema che può essere superato riprovando con la richiesta dopo un certo tempo, riprova con la richiesta usando il backoff esponenziale.
4. Essere diligenti: implementare la registrazione
In una situazione ideale, la tua integrazione funzionerebbe senza intoppi fin dal primo giorno e non ci sarebbe mai bisogno di risolvere problemi di nessun tipo.
Sfortunatamente, raramente è così. Quando i problemi si presentano, è importante che l'integrazione sia in grado di registrare le richieste e le risposte dell'API.
Avere accesso alle richieste e alle risposte base (inclusi i codici di errore dettagliati e i messaggi di errore) quando si verificano problemi con l'API, semplifica e velocizza la risoluzione dei problemi.
Gli esempi seguenti mostrano il tipo di informazioni che l'applicazione dovrebbe registrare per le richieste e le risposte dell'API:
Richiesta: verbo, URI, intestazione/i, corpo della richiesta
POST https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
Authorization: Bearer MY_TOKEN
Content-Type: application/json
Corpo della richiesta:
[
{
"title": "FIRST COLUMN - My New Column",
"index": 0,
"type": "TEXT_NUMBER"
},
{
"title": "FIRST COLUMN - My New Column",
"index": 1,
"type": "TEXT_NUMBER"
}
]
Risposta: codice di stato HTTP, corpo della risposta
Stato HTTP: 400 richiesta non valida
Corpo della risposta:
{
"errorCode": 1133,
"message": "Column titles are not unique among input columns.",
"detail": {
"columnTitle": "FIRST COLUMN - My New Column"
}
}
Spesso, avere accesso a queste informazioni ti consentirà di identificare e risolvere autonomamente il problema. Quando non è così, puoi contattare devrel@smartsheet.com per assistenza. Ti chiederemo le informazioni qui sopra relative alla richiesta e alla risposta per poter risolvere il problema.
Dovresti implementare la registrazione delle richieste e delle risposte dell'API non appena configuri la tua integrazione poiché questo ti consentirà un'esecuzione più efficace.
Inizia a realizzare la tua integrazione
Che tu sia attualmente nella fase di progettazione e compilazione di un'integrazione con Smartsheet o che tu abbia compilato un'integrazione in precedenza, nessun momento è migliore di questo per incorporare le best practice di cui abbiamo parlato in questo post.
Inoltre, ti incoraggiamo a sfruttare al massimo il Portale Smartsheet per gli sviluppatori per ottenere le risorse e le linee guida di cui abbiamo parlato in questo post, con lo scopo di ridurre il tempo necessario per ottenere familiarità con l'API Smartsheet e implementare con sicurezza la tua soluzione.
Iscriviti alla Newsletter Smartsheet IT per ricevere suggerimenti, strategie e idee incentrate sull'aiuto ai professionisti IT per aumentare l'impatto sulla propria attività.