Avalie APIs de forma rápida e fácil com o OpenAPI

Na Nexmo, publicamos especificações OpenAPI para todas as nossas APIs. Isso facilita aos desenvolvedores explorar, avaliar e integrar nossas APIs em suas próprias Applications. Continue lendo para saber mais sobre o OpenAPI e por que compartilhamos essas especificações de API com os desenvolvedores.

O que é o OpenAPI?

OpenAPI é uma forma legível por máquina de descrever uma API. É escrita em YAML ou JSON e descreve a finalidade geral, o mecanismo de autenticação e outros detalhes da API (se você já ouviu falar do Swagger, o OpenAPI é o sucessor dele). Também descreve cada um dos endpoints da API em detalhes. Por exemplo, aqui está um trecho da nossa API de Account, mostrando como você pode verificar o saldo da sua conta Nexmo:

/account/get-balance:
    servers:
      - url: "https://rest.nexmo.com"
    get:
      operationId: getAccountBalance
      summary: Get Account Balance
      description: Retrieve the current balance of your Nexmo account
      parameters:
        name: api_key
        description: Your Nexmo API key. You can find this in the [dashboard](${CUSTOMER_DASHBOARD_URL})
        in: query
        required: true
        schema:
          type: string
          example: abcd1234
        name: api_secret
        description: Your Nexmo API secret. You can find this in the [dashboard](${CUSTOMER_DASHBOARD_URL})
        in: query
        required: true
        schema:
          type: string
          example: ABCDEFGH01234abc

Como você pode ver, o formato da descrição da API é bastante detalhado. Isso porque ele precisa descrever uma API de forma tão clara que até mesmo as máquinas possam entendê-la. O exemplo mostrado aqui contém a URL, o verbo e os parâmetros necessários para obter informações sobre o saldo da conta. A especificação também fornece uma maneira de descrever os status das respostas e as cargas úteis que podem ser retornadas, tanto as bem-sucedidas quanto as demais!

Baixar uma especificação OpenAPI

As especificações OpenAPI são amplamente utilizadas pelas empresas fornecedoras de APIs. Essa especificação legível por máquina pode ser muito útil no ciclo de desenvolvimento, permitindo a geração automatizada de código, testes e bibliotecas SDK.

No entanto, a especificação OpenAPI se torna ainda mais útil quando é amplamente compartilhada fora da própria organização do provedor da API. Ela é um bom indicador das práticas modernas de API, e é muito mais rápido baixar um arquivo em formato padrão para usar em suas próprias ferramentas do que ter que vasculhar documentação desconhecida em busca de informações. Estamos vendo muitos provedores de API oferecendo especificações OpenAPI para suas APIs, e adoramos isso :)

Se você acessar uma página de referência da API da Nexmo, verá um botão como este:

A big blue Download OpenAPI 3 Description button

A documentação de referência da API é gerada a partir da própria especificação OpenAPI, e ao clicar no botão de download você obtém o arquivo YAML de origem. Você também pode encontrar todas as nossas especificações no GitHub.

Explore a API no Postman

O que mais gostamos de fazer com um arquivo OpenAPI que ainda não conhecemos é importá-lo para o Postman. Se você ainda não conhece essa excelente ferramenta, trata-se de um cliente HTTP muito bom, que é realmente valioso ao trabalhar com APIs (na verdade, é muito mais do que isso; confira você mesmo).

O Postman agora oferece suporte a arquivos OpenAPI v3. Você pode importar um arquivo ao criar uma coleção:

Shows the import dialog when creating a collection

A importação de uma especificação OpenAPI gerará uma “Coleção” pronta de solicitações de API, e cada endpoint já terá uma solicitação criada para você. Você pode adicionar rapidamente sua chave de API, seu segredo e quaisquer outros parâmetros necessários para essa solicitação e executá-la.

check balance postman

Acho que essa é uma maneira muito rápida de explorar uma API com a qual não estou familiarizado. Em vez de ter que ler a documentação e montar algumas chamadas de API de exemplo para tentar descobrir se essa API em particular atenderá às minhas necessidades, tudo está bem diante dos meus olhos.

Dica profissional: fique à vontade para experimentar isso agora com a API da Nexmo. Você precisa criar um Account primeiro, mas não se preocupe, ela já vem com um pequeno crédito gratuito para você testar.

Gere seu próprio SDK

Na Nexmo, disponibilizamos SDKs para servidores em seis e meia pilhas tecnológicas diferentes — mas nem todo provedor de API faz isso, ou talvez não ofereça a linguagem de programação que você está procurando. Como uma solução intermediária entre um SDK decente e nada, você pode usar um gerador de código para criar um wrapper básico para a API. Confira a seção “Geradores de SDK” em https://openapi.tools/#sdk para ver alguns exemplos.

Ter o SDK “real” ou um gerado pode acelerar bastante as integrações de API; os recursos de autocompletar no seu IDE são muito mais rápidos do que consultar a documentação a cada passo. Gerar um SDK para apenas uma parte da API também pode resultar em menos dependências ou em uma base de código menor, e, em algumas situações, isso faz muita diferença. Escolher um provedor de API que forneça a especificação OpenAPI é muito útil nesses cenários.

Nota do editor: Saiba mais sobre o OpenAPI

Se você tiver interesse em saber mais sobre o OpenAPI, por que não participa do nosso evento Vonage Campus em São Francisco? A Lorna (autora deste post) estará lá para dar uma palestra sobre a OpenAPI — e ela adora conversar sobre a OpenAPI em geral, então é uma ótima oportunidade para se encontrar com o pessoal da Nexmo e trocar ideias sobre APIs.