Documenta e verifica un'API dai suoi casi d'uso

Scegli le attività prima degli indirizzi

Elenco utilizza come trovare un prodotto, leggere la disponibilità, aggiornare un record o tracciare l'elaborazione. Definire persone e sistemi autorizzati per ogni operazione. Un'API di lettura pubblica e un'API amministrativa hanno requisiti di accesso diversi.

Preparare un esempio di richiesta e risposta per ogni attività essenziale utilizzando valori sintetici e campi spiegati. distinguere identificatori stabili, etichette, unità e date. Definire i dati mancanti invece di sostituire i valori plausibili con informazioni sconosciute.

descrivere un contratto esplicito

OpenAPI fornisce un formato di descrizione indipendente dalla lingua per le API HTTP, che copre operazioni, parametri, risposte e modelli. Scegli una versione supportata dai tuoi strumenti e conserva il documento con il progetto; La versione più recente non è automaticamente la soluzione giusta per ogni toolchain.

Limiti di utilizzo del documento, impaginazione, filtri, ordinazioni, errori e risposte vuote. Non trattare i COR come prova di autorizzazione. Rivedere le operazioni e i controlli di accesso a livello di oggetto con il team tecnico.

Test confini e autorizzazioni

Prova un oggetto esistente, un oggetto mancante, un parametro non valido e un elenco più lungo di una pagina. Controllare la pagina successiva per perdite o ripetizioni all'interno del modello di aggiornamento scelto. Limitazioni di stato che l'API non può garantire.

Usa gli account di prova con autorizzazioni diverse. Tentativo di letture e modifiche al di fuori dell'ambito consentito utilizzando dati sintetici. Registra gli stati attesi e i messaggi utili senza esporre tracce interne o segreti di configurazione.

Pianificare il cambiamento e il supporto

distinguere un campo aggiunto da un campo rimosso o un significato modificato. identificare i consumatori prima di un cambiamento incompatibile. Spiega il periodo di transizione e come rilevare le integrazioni ancora utilizzando il contratto precedente.

Fornire un esempio eseguibile per un ambiente di test, una matrice di test e un contatto tecnico. Metti in relazione gli errori osservati con esempi documentati dopo il rilascio. La documentazione limitata al caso ideale lascia gli integratori senza guida per i rifiuti e le interruzioni.

Documentazione primaria: Iniziativa OpenAPI - Specifiche.