Uma API é tão boa quanto sua documentação, portanto, verifique se a sua pode ser descoberta com instruções de alta qualidade e outros detalhes importantes.

Mais organizações estão aproveitando o poder das APIs para otimizar seus negócios. As APIs se tornaram uma maneira de agregar valor e fornecer um serviço extra.

Apesar de sua popularidade geral, nem toda API é um sucesso. A adoção e o uso de uma API determinam em grande parte seu sucesso. Para aumentar a adoção, sua API precisa ser fácil de encontrar e usar.

A melhor maneira de fazer isso é documentando sua API em detalhes. Isso inclui detalhar componentes críticos para torná-los mais fáceis de entender. Descubra alguns dos componentes que você deve incluir na documentação da API.

O que é a documentação da API?

A documentação da API é um conteúdo técnico que descreve uma API em detalhes. É um manual contendo todas as informações necessárias para trabalhar com a API. O documento cobre o ciclo de vida da API e instruções sobre como integrar e usar seus componentes.

instagram viewer

A documentação da API abrange descrições de recursos, endpoints, métodos, solicitações e exemplos de resposta. Também pode incluir guias práticos e tutoriais mostrando aos usuários como integrá-lo. Explorar cada seção oferece aos usuários uma compreensão sólida da integração e uso da API.

Editores como o Google Docs já foram amplamente usados ​​para documentação de API profissional. Hoje em dia, existem ferramentas mais avançadas como Document 360, Confluence e GitHub Pages. Essas ferramentas ajudam a integrar texto e código para fluxos de trabalho mais fáceis.

1. Visão geral e finalidade da API

A primeira etapa na documentação de uma API é permitir que os usuários saibam do que se trata. Inclua informações sobre o tipo de recursos que ele fornece. As APIs geralmente têm vários recursos que retornam, para que o usuário possa solicitar o que precisa.

A descrição é breve, geralmente de uma a três frases que descrevem o recurso. Descreva o recurso disponível, os terminais e os métodos anexados a cada terminal. Como desenvolvedor de API, você descreve melhor seus componentes, funcionalidade e caso de uso.

Aqui está um exemplo de descrição da API do Airbnb:

2. Métodos de Autenticação e Autorização

As APIs lidam com milhares de solicitações e enormes quantidades de dados. A autenticação é uma das maneiras de garantir que os dados de sua API e os usuários estejam protegidos contra hackers. Autenticação de API verifica a identidade de um usuário e lhes dá acesso a recursos.

Existem várias maneiras de garantir segurança de endpoint. A maioria das APIs usa uma chave de API. Esta é uma cadeia de caracteres que um usuário pode gerar no site e usar para autenticação.

A documentação da API deve orientar os usuários sobre como autenticar e autorizar suas identidades. O diagrama a seguir mostra as informações de autenticação da API do Twitter.

3. Endpoints, padrões de URI e métodos HTTP

Nesta seção, demonstre como acessar o recurso. Os endpoints mostram apenas o final do caminho, daí seu nome. Eles mostram o acesso ao recurso e métodos HTTP o endpoint interage, ou seja, GET, POST ou DELETE.

Um recurso provavelmente tem uma variedade de terminais. Cada um com um caminho e método diferente. Endpoints geralmente têm breves descrições de sua finalidade e um padrão de URL.

O exemplo de código a seguir mostra um endpoint de usuário GET no Instagram.

Me pega? campos={campos}&access_token={token de acesso}

4. Formatos de solicitação e resposta

Você deve documentar os formatos de solicitação e resposta para que o usuário saiba o que esperar. A solicitação é uma URL de um cliente solicitando um recurso, enquanto a resposta é um feedback do servidor.

Veja a seguir um exemplo de solicitação que você pode enviar para a API do LinkedIn.

PEGAR https://api.linkedin.com/v2/{service}/1234

E aqui está um exemplo de resposta que ele pode retornar:

{
 "id": 1234,
 "relatedEntity": "urna: li: relatedEntity: 6789"
}

5. Parâmetros e cabeçalhos

Você também deve documentar os parâmetros de seus endpoints, que são opções que você pode passar para eles. Os parâmetros podem ser um ID ou número que especifica a quantidade ou tipo de dados retornados em resposta.

Existem diferentes tipos de parâmetros, incluindo cabeçalho, caminho e parâmetros de string de consulta. Os endpoints podem conter diferentes tipos de parâmetros.

Você pode incluir alguns parâmetros como cabeçalhos de solicitação HTTP. Normalmente, eles são para fins de autenticação, como uma chave de API. Aqui está um exemplo de um cabeçalho com chaves de API:

cabeçalhos: {
 'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
 'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}

Você inclui parâmetros de caminho no corpo do endpoint diretamente na URL. Eles mostram ao usuário como e onde colocar os parâmetros e como a resposta aparecerá. As palavras entre chaves são parâmetros.

Você também pode usar dois-pontos ou outra sintaxe para representar os parâmetros do caminho.

/service/myresource/user/{user}/bicycles/{bicycleId}

Com parâmetros de consulta, você deve colocar um ponto de interrogação (?) antes da consulta em um terminal. Separe cada parâmetro depois disso com um e comercial (&). A Microsoft tem uma boa documentação sobre a Graph API.

6. Códigos de erro e tratamento de erros

Às vezes, as solicitações HTTP falham, o que pode deixar o usuário confuso. Inclua códigos de erro esperados na documentação para ajudar os usuários a entender os erros.

O LinkedIn fornece códigos de erro HTTP padrão para tratamento de erros:

7. Trechos de código de exemplo

Trechos de código são partes essenciais de sua documentação. Eles mostram aos usuários como integrar a API em vários idiomas e formatos. Inclua como instalar e integrar SDKs (kits de desenvolvimento de software) em vários idiomas na documentação.

RapidAPI tem bons exemplos de trechos de código para desenvolvedores:

9. Controle de versão de API e logs de alterações

O controle de versão da API é uma parte essencial do design de API. Ele garante a entrega de serviços ininterruptos aos seus usuários. O controle de versão pode aprimorar a API com novas versões sem afetar os aplicativos cliente.

Os usuários podem continuar usando versões mais antigas ou migrar para versões avançadas a tempo. Se houver novas alterações nos logs, inclua-as na documentação para que os usuários estejam cientes.

A API do Microsoft Graph possui logs de alterações bem documentados:

Finalmente, inclua contatos importantes na documentação para suporte e feedback. Isso garante que os usuários possam entrar em contato com você com relatórios de erros e informações sobre como melhorar a API.

O valor da documentação da API

Se você criar uma API para valor comercial, o consumo determinará seu sucesso. E para que os usuários consumam sua API, eles devem entendê-la.

A documentação dá vida a uma API. Ele explica os componentes em detalhes em linguagem simples que vende seu valor e uso para os usuários. Os usuários terão prazer em consumir sua API se tiverem uma ótima experiência de desenvolvedor.

Uma boa documentação também ajuda a simplificar a manutenção e o dimensionamento da API. As equipes que trabalham com a API podem usar a documentação para gerenciá-la.