Aggiornare dalla sorgente

Una specifica di API vive. Reimportare sovrascrivendo tutto farebbe perdere gli aggiustamenti apportati; reimportare accanto produrrebbe un duplicato. Restorm fa la terza cosa: calcola il delta.

Come funziona

Ogni importazione riuscita registra un’impronta della sorgente sulla cartella di variabili creata. Il pulsante Aggiorna della cartella recupera la sorgente, confronta le impronte e applica le differenze anziché ripartire da zero:

• le nuove operazioni vengono aggiunte, nel punto in cui le avrebbe collocate una nuova importazione;
• le operazioni modificate vedono i propri parametri completati con ciò che la specifica aggiunge;
• le operazioni che la specifica contrassegna come deprecate vengono segnalate e compaiono attenuate nell’albero;
• le operazioni scomparse dalla sorgente vengono segnalate come rimosse e compaiono barrate — restano eseguibili e non vengono mai eliminate;
• le modifiche apportate vengono conservate: nome, metodo, URL e valori inseriti non vengono mai sovrascritti.

Il principio: la specifica fa fede su ciò che descrive, l’utente fa fede sul resto.

Lo svolgimento completo — dov’è il pulsante, che cosa mostra la procedura guidata prima di applicare, che cosa accade alla documentazione — è descritto in Accesso e aggiornamento della documentazione di un’API importata.

Soltanto per le importazioni tramite URL

La risincronizzazione presuppone che Restorm conosca la sorgente. Solo le importazioni fatte da un URL ne registrano una; un’importazione da file o per incollaggio non è risincronizzabile, anche se il suo formato figura nell’elenco qui sotto.

Formati risincronizzabili

I formati interessati sono dodici:

• OpenAPI 3.x
• Swagger 2.0 (la stessa pagina del precedente, ma qui contato a parte: i due hanno una propria logica di risincronizzazione)
• GraphQL (SDL)
• gRPC — file .proto e reflection del server
• SOAP / WSDL
• OData
• AsyncAPI
• Postman
• Insomnia
• Bruno
• OpenRPC
• Smithy

Formati non risincronizzabili

HAR, cURL, PowerShell, REST Client, Thunder Client, Paw, HTTPie, RAML, WADL, Thrift, TypeSpec, API Blueprint, tRPC.

Per questi, una nuova importazione crea un nuovo albero: sta all’utente riavvicinare i due, oppure importare in una cartella dedicata.

Caso particolare: gRPC per reflection

Una richiesta gRPC importata per reflection porta un pulsante Aggiorna dalla reflection direttamente nella sua scheda: è la via più breve quando un servizio evolve durante lo sviluppo.