Especificação de API

Visão Geral

O desenvolvimento de APIs no DHuO segue a abordagem Design First, onde a primeira etapa do ciclo de vida é a criação da especificação da API. Também chamada de contrato da API ou API Spec, a especificação da API é um artefato técnico que documenta as características da API a ser disponibilizada para consumo. Atualmente o DHuO suporta a exposição de APIs HTTP (REST e SOAP). Para APIs REST, é adotado o padrão OpenAPI. Por meio dele são informadas todas as regras para que o consumidor consiga enviar e receber dados da API, como:

• Endereço de hospedagem da API (URL)
• Protocolos de comunicação (HTTP, HTTPS)
• Caminho dos recursos da API (paths)
• Ações disponíveis (Métodos HTTP)
• Estrutura de dados de envio (request payload)
• Estrutura de dados de retorno (response payload)
• entre outros

Uma vez criada, essa documentação pode ser utilizada para duas finalidades:

• configurar as políticas de gateway, responsáveis por expor cada recurso da API. Para saber mais sobre o processo de publicação de APIs no portal, acesse a seção Políticas de Gateway da API.
• ser publicada em um portal, para consulta pelos consumidores da API, juntamente com a documentação Markdown, caso exista. Para saber mais sobre o processo de publicação de APIs no portal, acesse a seção Publicação Dev Portal da API.

A interface da especificação é composta, basicamente, de 2 elementos:

• editor de especificação
• histórico de versões

Editor de especificação

OpenAPI (anteriormente conhecido como Swagger) é um padrão de especificação para definir e documentar APIs REST. É como um idioma universal que permite que diferentes sistemas e ferramentas entendam e interajam com uma API de forma consistente, como geração de código de interfaces para implementação dos endpoints, geração de scripts para consumo da API, entre outros.

O editor de especificação do DHuO fornece suporte tanto ao OpenAPI (versão 3.0), quando à sua versão mais antiga, Swagger (versão 2.0) e recomenda fortemente a adoção do OpenAPI. O editor também possui um modo de pré-visualização capaz de exibir a especificação da forma como ela será exibida nos portais onde for publicada.

Histórico de versões

O DHuO adota um modelo de versionamento automático de especificação, baseado no padrão de versionamento semântico. Neste contexto, existem dois tipos de especificação: a especificação base e a especificação versionada.

A especificação base diz respeito ao conteúdo mais recente da especificação. A partir da versão base, é possível criar versões da especificação e publicar em portais. A ação Salvar salva o conteúdo em rascunho, enquanto a ação Versionar salva o conteúdo (caso modificado) e gera uma versão estável da especificação a partir dele.

A especificação versionada diz respeito ao conteúdo de uma especificação estável e pronta para ser disponibilizada em um portal. A especificação versionada pode ter seu conteúdo atualizado, através da ação Salvar, desde que não esteja publicada em um portal.

Informação adicional

A especificação base é utilizada para configuração das políticas de gateway, enquanto a especificação versionada é utilizada para a publicação nos portais.

As versões seguem o formato vmajor.minor.patch, onde:

• major corresponde ao dígito major da versão da API
• minor representa a criação de versões derivadas da especificação base. A cada nova versão criada a partir da versão base (pela ação Versionar), esse dígito é incrementado
• patch representa a criação de versões geradas a partir de uma versão já publicada em um portal

Atenção!

A criação de novas versões de uma especificação ocorre apenas a partir da versão base.

Não é possível editar o conteúdo de uma versão caso ela esteja publicada em algum portal. Ao salvar, será criada uma nova versão, segundo as regras de versionamento. Caso não deseje criar uma nova versão, é possível remover a publicação dos portais, editá-la e publicá-la novamente.

Configuração

A especificação de uma API é gerenciada pela interface do estúdio da API. A partir da home, acesse o menu > APIs. Na página de APIs, visualize a API desejada e acesse o menu > Especificação.

Na página principal, Especificação, ela pode ser editada e versionada. Por padrão, o conteúdo da especificação base será exibido ao acessar a página.

Na página Histórico de versões as versões existentes da especificação podem ser acessadas e excluídas. Caso deseje visualizar o conteúdo de uma versão específica, acesse a lista de versões e abra a versão desejada.

Atenção!

Não é possível excluir uma versão de especificação caso ela esteja publicada em algum portal. É necessário remover a publicação de todos os portais para excluir uma versão de especificação.

Permissões

Apenas usuários com papel de administrador da organização (Org Admin) ou provedor de APIs (API Provider) podem alterar o conteúdo da especificação. Para saber mais, acesse a seção Papéis e permissões.