🥇Quindi, RAML o OAS (Swagger)?

Nel dinamico mondo dei microservizi, tutto può cambiare — qualsiasi componente può essere riscritto in un altro linguaggio, utilizzando framework e architetture diversi. Ciò che deve rimanere invariato sono solo i contratti, affinché sia possibile interagire con il microservizio dall'esterno su una base costante, indipendentemente dalle metamorfosi interne. Oggi parleremo del nostro dilemma nella scelta del formato di descrizione dei contratti e condivideremo gli artefatti trovati.

Post preparato da Anna Melekhova e Vladimir Lapatin

Microservizi. Nello sviluppo di Acronis Cyber Cloud abbiamo capito che non possiamo fare a meno dei microservizi. La progettazione di un microservizio è impossibile senza la formalizzazione di un contratto, che rappresenta l'interfaccia del microservizio.

Tuttavia, quando un prodotto contiene più di un componente e lo sviluppo del contratto diventa un'attività regolare, ci si inizia a chiedere come ottimizzare il processo. Diventa evidente che l'interfaccia (contratto) e l'implementazione (microservizio) devono corrispondere, che diversi componenti devono svolgere le stesse funzioni in modo uniforme e che, senza una centralizzazione di tutte queste decisioni, ogni squadra si troverà a spendere tempo ripetutamente per ottenerle.

Schema dei microservizi di Amazon da un tweet di Werner Vogels, CTO di Amazon
Qual è dunque il dilemma? De facto ci sono due modi di interazione tra microservizi – HTTP Rest e gRPC di Google. Non volendo essere coinvolti nel stack tecnologico di Google, abbiamo scelto HTTP Rest. Le annotazioni sui contratti HTTP REST sono per lo più descritte in uno dei due formati: RAML e OAS, precedentemente noto come Swagger. Pertanto, ogni squadra di sviluppo si trova di fronte alla necessità di scegliere uno degli standard. Ma, come è emerso, effettuare questa scelta può rivelarsi molto difficile.

A cosa servono le annotazioni?

L'annotazione è necessaria affinché l'utente esterno possa facilmente comprendere cosa si può fare con il proprio servizio attraverso la sua interfaccia HTTP. Cioè, a un livello di base, l'annotazione dovrebbe contenere almeno un elenco delle risorse disponibili, i relativi metodi HTTP, i corpi delle richieste, l'elenco dei parametri, l'indicazione degli header necessari e supportati, nonché i codici di risposta e i formati delle risposte. Un elemento estremamente importante dell'annotazione del contratto è anche la loro descrizione verbale (“cosa succede se si aggiunge questo query-parameter alla richiesta?”, “in quale caso verrà restituito il codice 400?”)

Tuttavia, quando si tratta di sviluppare un gran numero di microservizi, si desidera estrarre ulteriore valore dalle annotazioni scritte. Ad esempio, sulla base di RAML/Swagger, è possibile generare sia codice client che server in un'enorme varietà di linguaggi di programmazione. Inoltre è possibile ottenere automaticamente la documentazione per il microservizio e caricarla sul proprio developer-portal :).

Esempio di descrizione strutturata del contratto

Raramente si incontra la pratica di testare i microservizi sulla base delle descrizioni dei contratti. Se hai scritto sia l'annotazione che il componente, puoi creare un test automatico che verifica l'adeguatezza del funzionamento del servizio con diversi tipi di dati in ingresso. Il servizio restituisce un codice di risposta non descritto nell'annotazione? Sarà in grado di gestire correttamente dati palesemente errati?

Inoltre, una realizzazione di qualità non solo dei contratti stessi, ma anche degli strumenti per visualizzare le annotazioni consente di semplificare il lavoro con il microservizio. Cioè, se l'architetto ha descritto accuratamente il contratto, sulla base di esso, designer e sviluppatori potranno implementare il servizio in altri prodotti senza costi di tempo aggiuntivi.

Per il funzionamento di strumenti aggiuntivi, sia RAML che OAS hanno la possibilità di aggiungere metadati non previsti dallo standard (per esempio, così facendo in OAS).

In generale, il campo per la creatività nell'applicazione dei contratti ai microservizi è enorme… almeno teoricamente

Confronto tra una lucertola e un riccio

Attualmente, la principale direzione di sviluppo in Acronis è l'evoluzione di Acronis Cyber Platform. Acronis Cyber Platform rappresenta nuovi punti di integrazione di servizi di terze parti con Acronis Cyber Cloud e la parte agent. Anche se le nostre API interne, descritte in RAML, ci soddisfacevano, la necessità di pubblicare l'API ha di nuovo sollevato la questione della scelta: quale standard di annotazioni è meglio utilizzare per il nostro lavoro?

Inizialmente sembrava che ci fossero due soluzioni — le più diffuse erano RAML e Swagger (o OAS). Ma in realtà si è rivelato che le alternative sono almeno 3 o più.

Da un lato c'è RAML, un linguaggio potente ed efficiente. Presenta una buona implementazione della gerarchia e dell'ereditarietà, rendendo questo formato più adatto per grandi aziende che necessitano di molte descrizioni, cioè non un solo prodotto, ma molti microservizi con parti comuni nei contratti, come schemi di autenticazione, tipi di dati identici e corpi di errore.

Tuttavia, lo sviluppatore di RAML, la società Mulesoft, si è unita al consorzio Open API, che si occupa dello sviluppo Swagger. Pertanto, lo sviluppo di RAML è stato sospeso. Per immaginare il formato evento, si potrebbe pensare a come i manutentori dei componenti principali di Linux siano andati a lavorare per Microsoft. Tale situazione crea presupposti per l'uso di Swagger, che si sviluppa dinamicamente e, con la sua terza versione, sta quasi raggiungendo RAML in termini di flessibilità e funzionalità.

Se non fosse per un piccolo particolare...

A quanto pare, non tutte le utilità open-source sono state aggiornate alla versione OAS 3.0. Per i microservizi su Go, il problema più critico è l'assenza di adattamento del go-swagger alla nuova versione dello standard. Tuttavia, la differenza tra Swagger 2 e Swagger 3 è enorme. Ad esempio, nella terza versione gli sviluppatori:

hanno migliorato la descrizione degli schemi di autenticazione
hanno completato il supporto per JSON Schema
hanno potenziato la possibilità di aggiungere esempi

La situazione diventa divertente: nella scelta dello standard, bisogna considerare RAML, Swagger 2 e Swagger 3 come alternative separate. Solo Swagger 2 ha un buon supporto per gli strumenti OpenSource. RAML è molto flessibile... e complesso, mentre Swagger 3 è poco supportato dalla comunità, il che significa che dovrete fare affidamento su strumenti di sviluppo interno o soluzioni commerciali, che di solito sono piuttosto costose.

Inoltre, mentre in Swagger ci sono molte funzionalità interessanti, come un portale pronto editor.swagger.io, sul quale è possibile caricare le annotazioni e ottenere una visualizzazione con descrizioni dettagliate, link e relazioni, per il più fondamentale e meno amichevole RAML non esiste una simile opportunità. Certo, è possibile cercare tra i progetti su GitHub per trovare un'alternativa e implementarla da soli. Tuttavia, in ogni caso, qualcuno deve occuparsi della manutenzione del portale, il che non è molto conveniente per un utilizzo di base o per scopi di test. Inoltre, Swagger è più "pragmatico" o liberale: può essere generato da commenti nel codice, il che chiaramente contraddice il principio API first e non è supportato da nessuno degli strumenti RAML.

In passato abbiamo iniziato a lavorare con RAML, considerando il linguaggio più flessibile, e alla fine abbiamo dovuto fare molte cose manualmente. Ad esempio, in uno dei progetti utilizziamo uno strumento ramlfications nei test unitari, che supporta solo RAML 0.8. Così abbiamo dovuto aggiungere delle soluzioni temporanee affinché lo strumento potesse "gestire" RAML versione 1.0.

E c'è davvero bisogno di scegliere?

Dopo aver lottato con l'estensione dell'ecosistema di soluzioni per RAML, siamo giunti alla conclusione che dobbiamo convertire RAML in Swagger 2 e condurre tutta l'automazione, verifica, test e successiva ottimizzazione lì. È un buon modo per sfruttare sia la flessibilità di RAML che il supporto degli strumenti della comunità di Swagger.

Per risolvere questo compito, esistono due strumenti OpenSource che dovrebbero garantire la conversione dei contratti:

oas-raml-converter – uno strumento attualmente non supportato. Durante l'utilizzo, abbiamo scoperto che presenta diversi problemi con RAML complessi, distribuiti su un gran numero di file. Questo programma è scritto in JavaScript e svolge una visita ricorsiva dell'albero sintattico. A causa della tipizzazione dinamica, risulta difficile districarsi in questo codice, quindi abbiamo deciso di non perdere tempo a scrivere patch per un'utilità morente.
webapi-parser — uno strumento della stessa azienda che si propone di convertire tutto e in qualsiasi direzione. Attualmente dichiara supporto per RAML 0.8, RAML 1.0 e Swagger 2.0. Tuttavia, al momento della nostra ricerca, lo strumento era ancora ESTREMAMENTE grezzo e inutilizzabile. Gli sviluppatori stanno creando una sorta di IR, il che permetterà loro in futuro di aggiungere rapidamente nuovi standard. Ma al momento tutto questo semplicemente non funziona.

E queste non sono nemmeno tutte le difficoltà con cui ci siamo confrontati. Uno dei passaggi del nostro pipeline è la verifica che RAML nel repository sia conforme alla specifica. Abbiamo provato diverse utilità. Sorprendentemente, tutte si sono lamentate delle nostre annotazioni in vari punti, con parole diverse e completamente inappropriate. E non sempre aveva senso :).

Alla fine ci siamo concentrati su un progetto ormai obsoleto, che presenta anche una serie di problemi (si blocca senza motivo, ha difficoltà con le espressioni regolari). Pertanto, non abbiamo trovato un modo per risolvere i problemi di validazione e conversione utilizzando strumenti gratuiti, e abbiamo deciso di utilizzare un software commerciale. In futuro, quando gli strumenti OpenSource saranno più sviluppati, la soluzione a questo problema potrebbe diventare più semplice. Nel frattempo, il tempo e le risorse necessarie per "aggiustare" ci sono sembrati più significativi rispetto al costo del servizio commerciale.

Conclusione

Dopo tutto ciò, abbiamo sentito il bisogno di condividere la nostra esperienza e sottolineare che, prima di scegliere uno strumento per la descrizione dei contratti, è fondamentale definire chiaramente cosa si desidera da esso e quale budget si è disposti a investire. A prescindere dagli strumenti OpenSource, ci sono già molti servizi e prodotti che possono aiutare a effettuare controlli, conversioni e validazioni. Tuttavia, sono costosi, e talvolta, molto costosi. Per una grande azienda, tali spese possono essere tollerabili, ma per una startup possono rappresentare un carico significativo.

Definire un insieme di strumenti che utilizzerete in seguito. Ad esempio, se avete bisogno solo di visualizzare un contratto, sarà più semplice utilizzare Swagger 2, che ha una bella API, mentre con RAML dovrete configurare e mantenere il servizio da soli.
Maggiore sarà il numero delle vostre esigenze, più ampia sarà la richiesta di strumenti, e questi sono diversi per piattaforme differenti. È meglio familiarizzare da subito con le versioni disponibili, per fare una scelta che minimizzi i vostri costi in futuro.

Tuttavia, bisogna riconoscere che tutti gli ecosistemi esistenti al giorno d'oggi sono imperfetti. Pertanto, se in azienda ci sono appassionati che amano lavorare in RAML perché “permette di esprimere le idee in modo più flessibile”, o viceversa, preferiscono Swagger perché “è più chiaro”, è meglio lasciarli lavorare con ciò che conoscono e desiderano, poiché gli strumenti di entrambi i formati richiedono modifiche manuali.

Per quanto riguarda la nostra esperienza, nei prossimi post parleremo di quali controlli statici e dinamici eseguiamo sulla nostra architettura RAML-Swagger, oltre a quale documentazione generiamo dai contratti e come funziona tutto questo.

Solo gli utenti registrati possono partecipare al sondaggio. Accedi, per favore.