BT

Disseminando conhecimento e inovação em desenvolvimento de software corporativo.

Contribuir

Tópicos

Escolha a região

Início Artigos Usando a OpenAPI para criar APIs inteligentes que ajudam os desenvolvedores

Usando a OpenAPI para criar APIs inteligentes que ajudam os desenvolvedores

Favoritos

Pontos Principais

  • As especificações de descrição da API, como a OpenAPI, são uma ferramenta crítica a ser usada para transferir o ônus de gerenciar, documentar, e executar as APIs para máquinas de computação e liberar desenvolvedores o máximo possível.
  • A OpenAPI 3.0 agora permite expressividade adicional que pode permitir que as máquinas trabalhem ainda mais para nós.
  • A OpenAPI pode gerar uma poderosa automação de testes, pode produzir simulações realistas, e até gerar ligações nativas que abstraem a complexidade do desenvolvedor.
  • Existem benefícios subutilizados da OpenAPI, como links e retornos de chamada, que podem ser usados para que os desenvolvedores abstraiam da documentação e vão direto ao código.

Esta é a era da API. Até empresas não-tecnológicas (se ainda existem) tratam as APIs como um produto-chave. Cada vez mais as empresas usam APIs como tese organizadora, a unidade básica pela qual diferentes equipes compartilham seu trabalho e se comunicam. Muitos procuram imitar o sucesso da Amazon, cuja ascensão implacável foi alimentada por APIs, internas e externas. No reconstrução de 2020 do The Graduate, a única palavra de conselho para um jovem Dustin Hoffman recriado digitalmente que contemplava seu futuro seria "APIs". Infelizmente, a única pequena descrição mais atraente da OpenAPI que eu achei foi: "uma especificação para arquivos de interface lidos por máquinas". Sob a simplicidade de um slogan existe uma tecnologia muito útil e pragmática. Sim, ela lhe permite descrever APIs de uma maneira que as máquinas possam consumir, mas o que as máquinas podem fazer é incrivelmente útil para as equipes que criam APIs, bem como para os desenvolvedores de software que as utilizam.

Aprendizes entusiasmados

Quando eu era criança, as referências à API eram encadernadas em livros e eu as devorava. O Guia do desenvolvedor, Programação em Palm, Especificação da API Java 3D - sim, sim e sim. Tim O'Reilly, tome meu dinheiro! Livros como esses eram sobre como aprender, não apenas um overview sobre os sistemas ou plataformas que você queria manipular, mas também os detalhes de como fazer isso acontecer, a referência da API. Esse material foi predominantemente para plataformas on-line, e é preciso muito esforço para ensinar mesmos os alunos mais entusiasmados.

Educar as pessoas que queremos que usem as APIs que construímos é tão importante quanto criar as próprias APIs.

O termo API abrange muito terreno, então para aprimorar um pouco vou me concentrar exclusivamente nas APIs baseadas em HTTP. Eu chamaria isso de REST - e muitos o fazem incorretamente - mas o REST é realmente um pouco mais restrito e um subconjunto de APIs da web. Isso não minimiza a importância de outras APIs (como as que se pode encontrar em um SDK), mas as Web APIs estão proliferando a uma taxa sem precedentes, e as APIs em nossas redes privadas se parecem cada vez mais com as APIs para serviços em nuvem na Internet aberta. Também não estou falando de antiguidades, como WSDL, ou de novos gostos como o GraphQL (apesar de falar sobre isso mais tarde). Apenas as APIs simples da Jane que quase todo fornecedor de SaaS pública.

Em vez da interface para APIs ficar exclusivamente no código, muitos desenvolvedores se apegaram à necessidade de gerar uma descrição programática que alimentasse documentos, registro, geração de código, etc.

A OpenAPI não é a única especificação para descrever APIs, mas é o que parece estar ganhando destaque.

Começou como Swagger e recebeu o nome de OpenAPI com sua doação para a iniciativa OpenAPI (obrigado, SmartBear!).

O RAML e o API Blueprint têm seus próprios aderentes (mas parecem estar em declínio).

Outras, como a AWS, Google, e Palantir, usam suas próprias especificações de API porque são anteriores a esses outros padrões, têm requisitos diferentes, ou consideram que as especificações da OpenAPI não são suficientemente restritivas.

Vou me concentrar na OpenAPI aqui porque sua crescente popularidade gerou toneladas de ferramentas (incluindo nossa própria camada SQL para APIs).

O ato de descrever uma API com a OpenAPI é o primeiro passo no processo pedagógico. Sim, a documentação para humanos ler é uma saída óbvia, mas a OpenAPI também permite educar máquinas sobre o uso de nossas APIs para simplificar ainda mais as coisas para os consumidores humanos e operar de forma autônoma. À medida que colocamos mais e mais informações na OpenAPI, podemos começar a transferir a carga dos humanos para as máquinas e para as ferramentas que elas usam. Com tantas APIs e muito outras coisas para os desenvolvedores de software saberem, nos tornamos preguiçosos por necessidade. APIs são um produto; reduzir o atrito para os desenvolvedores é um grande negócio.

OpenAPI 101

Um arquivo OpenAPI pode ser especificado em JSON ou YML; aqui está um trecho da documentação da OpenAPI do Strava:

  "paths": {
    "/athletes/{id}/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Get Athlete Stats",
        "description": "Returns the activity stats of an athlete.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The identifier of the athlete. Must match the authenticated athlete.",
            "required": true,
            "type": "integer"
          },
          {
            "$ref": "#/parameters/page"
          },
          {
            "$ref": "#/parameters/perPage"
          }
        ],
        "tags": [
          "Athletes"
        ],

Você pode escrever documentos com ferramentas (ou manualmente) ou gerá-los a partir do código em praticamente qualquer idioma. Aqui está um exemplo em Java que inclui anotações OpenAPI juntamente com anotações JAX-RS.

@GET
    @Path("/{username}")
    @Operation(summary = "Get user by user name",
            responses = {
                    @ApiResponse(description = "The user",
                            content = @Content(mediaType = "application/json",
                                    schema = @Schema(implementation = User.class))),
                    @ApiResponse(responseCode = "400", description = "User not found")})
    public Response getUserByName(
            @Parameter(description = "The name that needs to be fetched. Use user1 for testing. ", required = true) @PathParam("username") String username)
            throws ApiException {
        User user = userData.findUserByName(username);
        if (null != user) {
            return Response.ok().entity(user).build();
        } else {
            throw new NotFoundException(404, "User not found");
        }
    }

A saída óbvia da OpenAPI é a documentação. Um benefício óbvio é que (com um fluxo de trabalho razoavelmente inteligente) as coisas permanecem atualizadas.

<blockquotes>

Documentação desatualizada é ambos embaraçoso e enfurecedor.

</blockquotes>

A OpenAPI permite que seus documentos fiquem muito mais sofisticados. Em vez de apenas descrever os detalhes da API, pode adicionar componentes úteis, como um explorador interativo, ou gerar automaticamente logs de alterações.

Afastando-se do uso humano direto, a OpenAPI pode impulsionar servidores para simuladores que publicam APIs com base no que você descreveu. Essas APIs simuladas podem responder de acordo com o esquema na especificação, bem como com exemplos específicos também codificados na especificação. Isso permite que equipes internas simulem o funcionamento antes que a API seja totalmente criada, e que desenvolvedores externos testem o uso programático de sua API sem enviar spam aos seus servidores (ou antes de obterem acesso autenticado).

Um dos nossos primeiros usos da OpenAPI foi gerar ligações de código nativas. No nosso caso, geramos ligações TypeScript para nosso front-end para interagir com o back-end. Isso moveu o processo de aprendizado da API para fora do código e da documentação, e para dentro da IDE. Em vez de olhar o código do servidor para descobrir como ele funcionava, poderíamos nos apoiar no editor para nos mostrar a interface de várias APIs, incluindo os tipos adequados. A publicação de uma especificação OpenAPI para sua API permite que os desenvolvedores aprendam sobre ela usando técnicas de exploração de código (caso você goste do Vim).

OpenAPI 3.0

A iniciativa OpenAPI publicou a versão 3.0 há pouco mais de um ano. Inclui alguns recursos bastante interessantes, mas ainda subutilizados. Mais importante, ela expandiu sua capacidade de descrever APIs. O Swagger começou como um subconjunto intencionalmente opinativo - o que deveria ser feito em vez de tudo o que poderia ser feito em termos de especificação e parametrização de APIs. Seria ótimo ver a OpenAPI continuar esse progresso nas versões subsequentes. A versão 3.0 também introduziu duas novas partes interessantes de metadados: links e retornos de chamada.

Links - Geralmente, os resultados de uma chamada de API podem ser usados como entradas para outra chamada de API. Você provavelmente já viu APIs que literalmente incluem links no corpo da resposta. O recurso de links da OpenAPI adiciona metadados estáticos que descrevem as ligações entre diferentes APIs, como usar a saída de uma API como entrada para outra. Isso está avançando no território do GraphQL, que codifica explicitamente as ligações (arestas) entre entidades. Os criadores e as ferramentas da especificação de APIs ainda parecem não usar muito os links, mas existem inúmeras possibilidades: documentação navegada por links, exploradores de API interativos, ou camadas de conversão automática do GraphQL. Seria ótimo ver mais documentos da OpenAPI usando links e melhores ferramentas para especificar links.

Retornos de chamadas - Ao registrar um webhook, você normalmente passa uma URL como uma string. O serviço invocará essa API. A OpenAPI 3.0 permite descrever a assinatura do retorno de chamada, os parâmetros que ele deve esperar. Novamente, isso é muito útil para tirar os desenvolvedores da documentação e poder descobrir mais através do código - que é onde eles querem estar!

E ainda mais

A adoção da OpenAPI alivia a carga dos criadores de API que tentam educar seus usuários com eficiência. Porém, é mais eficaz quando permite que os desenvolvedores não apenas aprendam melhor, mas aprendam menos. É tão difícil ter a atenção dos desenvolvedores que, quando a temos, queremos educá-los sobre tópicos importantes, em vez de detalhes logísticos automatizáveis. Há mais que a OpenAPI poderia fazer para se concentrar em educar as máquinas que os desenvolvedores usam e não os próprios desenvolvedores. Considere a paginação, por exemplo. Veja como a API do Google Agenda ensina os usuários a paginar através de eventos da agenda:

inputs:

pageToken

string

Token especificando qual página de resultado retornar. Opcional.

outputs:

nextPageToken

string

Token usado para acessar a próxima página deste resultado. Omitido se nenhum resultado adicional estiver disponível, nesse caso, o nextSyncToken é fornecido.

Para uma pessoa - lendo atentamente - é perceptível que deve-se pegar a saída do nextPageToken e conectá-la à entrada pageToken para cada chamada sucessiva, mas não há como a OpenAPI (ou no Serviço de descoberta do Google para formatação de documentos) expressar essa semântica .

Outro padrão comum em que a OpenAPI poderia expandir sua expressividade envolve operações que podem levar segundos ou mais para serem concluídas. Considere criar uma instância de máquina virtual em uma nuvem pública. Uma chamada inicia o processo de criação da instância; outra é necessária para determinar quando a instância está em funcionamento. Da documentação da AWS para EC2 RunInstances:

"Uma instância está pronta para uso quando estiver no estado de execução. Você pode verificar o estado da sua instância usando DescribeInstances."

Seria uma grande melhoria na qualidade de vida dos desenvolvedores se a especificação da API codificasse essas semânticas e as ferramentas que eles usassem pudessem abstraí-las, esses detalhes meticulosos, consumíveis por máquina, para que os desenvolvedores humanos possam aprender menos.

Resumindo

Se você criou uma API ou está criando uma nova API, comece a usar uma especificação de descrição da API. A OpenAPI é a opção cada vez mais popular, mas se isso não funcionar, você ainda escolhe alguma coisa (e deixe o pessoal da OpenAPI saber por que não deu certo). Quanto mais você permanecer no caminho mais amaciado, maiores serão os benefícios do ecossistema de ferramentas.

Como começar a usar a OpenAPI (ou algo semelhante)? O processo pelo qual se descreve uma API tem uma escolha surpreendentemente controversa. Os mais fortes entram na batalha sob o grito de guerra de "primeiro o contrato!". Para eles, a especificação da API deve ser onde os projetos da API começam, a partir daí, pode gerar código stub, clientes etc. Mais pragmaticamente para APIs existentes, existem ferramentas para estruturas da Web comuns para extrair especificações do código (em alguns casos, auxiliado por anotações ou decoração adicionais).

Seja contrato primeiro ou código primeiro, realmente depende de seus próprios processos. Para grandes empresas, 'contrato primeiro' pode ser o caminho certo para colocar as equipes de servidores e clientes de maneira inequívoca na mesma página. Enquanto o código do servidor está sendo gravado, as equipes de cliente podem gravar em simulações geradas automaticamente. Para grupos em que cliente e servidor são desenvolvidos juntos ou onde a API é o produto, pode ser suficiente que o código seja a fonte da verdade. Da mesma forma, para APIs existentes, o barco já pode ter saído com 'contrato primeiro'. Nesses casos, pode-se derivar a documentação da OpenAPI de frameworks comuns (em alguns casos com a ajuda de decoração ou anotação adicional).

Agora que você obteve a descrição da API, a coisa mais importante a fazer é publicá-la. Publique e mantenha-a atualizado. Aproveite ao máximo o uso interno: gere stubs de servidor e código do cliente, crie simulações automáticas e, claro, gere seus documentos para consumo humano. Mas, publicando o próprio documento da API, você instrui as máquinas que os desenvolvedores usam para consumir suas APIs. Os stubs, simuladores, e testes que eles podem gerar hoje significam que os desenvolvedores passam menos tempo aprendendo sobre os detalhes de baixo nível da sua API e mais tempo construindo. À medida que a OpenAPI e seu ecossistema de ferramentas evoluem, os consumidores de suas APIs aprendem menos conforme as bibliotecas, estruturas e plataformas que eles usam ficam mais inteligentes.

Sobre o autor

Adam Leventhal é o fundador e CEO da Transposit. Antes de fundar a Transposit em 2016, Adam era CTO da Delphix, onde liderou equipes de desenvolvimento, controle de qualidade, suporte, gerenciamento de programas, gerenciamento de produtos, recrutamento estagiários, e desenvolvimento avançado, e escalou a equipe de engenharia de 10 para mais de 100. Enquanto Adam era um engenheiro da equipe de desenvolvimento do kernel do Solaris na Sun Microsystems, ele foi um dos três autores do DTrace pelo qual recebeu o prêmio de excelência técnica do Presidente da Sun em 2004, foi nomeado um dos inovadores da InfoWorld em 2005 e recebeu as principais honras em inovação do jornal Wall Street, em 2006. Adam desenvolveu vários códigos para análise de depuração e post-mortem e continua seu trabalho no rastreamento de novos usuários para expandir a amplitude e profundidade da visão do sistema do DTrace. Adam ingressou na Sun depois de se formar com louvor na Brown University em 2001, com um diploma em matemática e ciências da computação.

Avalie esse artigo

Relevância
Estilo/Redação

Conteúdo educacional

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

BT