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.
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
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.
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.