Supponiamo che il server limiti un campo JSON a un insieme di valori enumerati.
es. una richiesta POST a /user si aspetta un oggetto con un campo chiamato gender che dovrebbe essere solo "maschio", "femmina" o "n / a".
Una libreria di wrapper dovrebbe assicurarsi che il campo sia impostato correttamente prima di effettuare la richiesta?
Se hai a che fare con una risorsa di rete (come implicitamente con un'API REST), allora ha molto senso dal punto di vista dell'utente di fare più pre-validazione possibile, per salvare il sovraccarico della rete round-trip alla loro esperienza utente.
Inoltre, in alcuni casi l'API verrà limitata al numero di richieste che effettuerai o ti verrà addebitato in base a un volume. In entrambi i casi, ha molto senso pre-validare prima dell'invio.
Quindi, in generale, direi di sì, convalidare prima di inviare ogni volta che sai cosa si aspetta l'API.
IMO questo dipende principalmente da un dettaglio: stai ospitando il wrapper o è solo una libreria client?
Per me in entrambi i casi sembra che dipenda da te, se non stai facendo alcuna validazione (contro l'API avvolta ovviamente, altrimenti DEVI sterilizzare i tuoi input!) puoi semplicemente trovare un modo conveniente per accedere detto servizio, ma non ci sarà molto vantaggio, specialmente se non aggiungete troppo in alto, ma semplicemente estendete la curva di apprendimento poiché le persone devono leggere la vostra documentazione invece di quella ufficiale, dovete pensare alla compatibilità con versioni future dell'API che si sta completando, ecc.
Se stai scrivendo un client che avvolge un altro client sembra che tu possa semplicemente fare alcuni controlli di base, ma fare affidamento sull'implementazione sottostante per sapere come gestire le cose. Se stai scrivendo un wrapper ospitato, probabilmente dovresti avere quei controlli in posto e invece di agire come un semplice proxy per il funzionario, puoi fornire in modo trasparente la compatibilità - nota anche come bridge / compat layer - nel qual caso sarà abbastanza buono avere i tuoi assegni in essere
Le cose possono essere utili se l'API di destinazione utilizza effettivamente uno schema (JSON-API, WSDL, XSL, JsonSchema, Swagger / OpenAPI e simili) poiché è possibile ottenere una convalida dinamica senza troppo impegno straordinario. Ci sono molte librerie in grado di gestire l'analisi e la convalida per te, quindi potresti non dover fare tutto questo. MA devi assolutamente farlo se l'API che stai tagliando è scarsamente documentata, non fornisce codici di errore informativi (tutti conosciamo un fornitore che ti dà "400 - Richiesta non valida - Qualcosa di inaspettato è accaduto")
In caso di dubbi, prova a ricordare come lo facciamo sul web
Should a wrapper library make sure that the field is set correctly before making the request?
L'analogico web di questo è un modulo html, che invierà dati application / x-www-form-urlencoded, dove la rappresentazione del modulo stesso include una descrizione di un controllo di input che fornisce sia il nome di un parametro che un elenco di valori previsti.
Il browser web, a sua volta, produrrebbe un'interfaccia utente con elementi visivi che illustrano chiaramente l'intervallo di valori consentiti e costruirà il corpo della richiesta appropriata dalla selezione effettuata dall'operatore umano.
Tecnicamente, la gamma di scelte non deve essere inclusa nella rappresentazione; un tipo di supporto che descrive l'intervallo di valori consentiti. Penso che scoprirai che la progettazione del supporto per il cambiamento nelle tue definizioni dei tipi di media andrà a buon fine nel lungo periodo.
Naturalmente, non tutti gli interpreti applicano gli intervalli descritti all'interno delle rappresentazioni. arricciatura, per esempio, non impedirà un errore di ortografia se provi a creare la tua risposta.
Non è obbligatorio che la libreria wrapper supporti la descrizione delle richieste con i primitivi. Se pensi che l'introduzione di un tipo di valore di genere aumenterà l'adozione della biblioteca o migliorerà l'esperienza di utilizzo, allora dovresti assolutamente farlo. Scambi: il percorso felice diventa più facile da usare, i casi limite diventano più difficili.
Sì. Idealmente sarebbe una convalida del tempo di compilazione. Quindi non potresti nemmeno scrivere il codice che ha chiamato la funzione con un tipo errato.
Leggi altre domande sui tag open-source api-design rest libraries