Atualizar a partir da origem

Uma especificação de API tem vida. Voltar a importar apagando tudo faria perder os seus ajustes; voltar a importar ao lado produziria um duplicado. O Restorm faz a terceira coisa: calcula o delta.

Como funciona

Cada importação bem-sucedida registou uma impressão digital da origem na pasta de variáveis criada. O botão Atualizar da pasta obtém a origem, compara as impressões digitais e aplica as diferenças em vez de recomeçar do zero:

• as novas operações são adicionadas, no lugar onde uma importação nova as teria colocado;
• as operações alteradas veem os seus parâmetros completados com o que a especificação acrescenta;
• as operações que a especificação marca como obsoletas são sinalizadas e aparecem esmaecidas na árvore;
• as operações desaparecidas da origem são sinalizadas como retiradas e aparecem rasuradas — continuam executáveis e nunca são eliminadas;
• as suas alterações são conservadas: nome, método, URL e valores introduzidos nunca são substituídos.

O princípio: a especificação manda no que descreve, você manda no resto.

O percurso completo — onde está o botão, o que o assistente mostra antes de aplicar, o que acontece à documentação — está descrito em Acesso e atualização da documentação de uma API importada.

Apenas para as importações por URL

A ressincronização pressupõe que o Restorm conheça a origem. Só as importações feitas a partir de um URL registam uma; uma importação a partir de um ficheiro ou por colagem não é ressincronizável, mesmo que o seu formato conste da lista abaixo.

Formatos ressincronizáveis

Doze formatos estão em causa:

• OpenAPI 3.x
• Swagger 2.0 (a mesma página que o anterior, mas contado à parte aqui: cada um tem a sua própria lógica de ressincronização)
• GraphQL (SDL)
• gRPC — ficheiro .proto e reflexão do servidor
• SOAP / WSDL
• OData
• AsyncAPI
• Postman
• Insomnia
• Bruno
• OpenRPC
• Smithy

Formatos não ressincronizáveis

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

Para esses, uma nova importação cria uma nova árvore: cabe-lhe a você aproximar as duas, ou importar para uma pasta dedicada.

Caso particular: gRPC por reflexão

Um pedido gRPC importado por reflexão tem um botão Atualizar a partir da reflexão diretamente no seu separador: é o caminho mais curto quando um serviço evolui durante o desenvolvimento.