Materiais gratuitos

Como fazer uma API com design amigável

Se o seu objetivo é desenvolver uma nova API para o seu ERP, tenha em mente que ela precisa ser amigável. Vamos mostrar como!

Por lais
Como_fazer_uma_API_com_design_amigavel
Tempo de leitura: 4 minutos

Configurar uma API não precisa ser algo complexo. Apesar de ser uma funcionalidade cada vez mais comum na economia digital, infelizmente os processos de diversas integrações ainda são complicados e contam com documentações pobres. Isso gera um trabalho a mais para o desenvolvedor e um atrito entre a empresa que está oferecendo esse serviço e a que está contratando.
Se o seu objetivo é desenvolver uma nova API para o seu ERP, tenha em mente que ela precisa ser amigável. Mas como fazer isso? O objetivo deste texto é justamente te mostrar como oferecer uma Application Programming Interface (API) acessível.
Antes de mais nada, vale lembrar que é muito difícil criar uma solução que agrade todos os desenvolvedores que vão utilizá-la. Porém, existem algumas ações que podem facilitar muito a vida dos usuários. Para desenvolver uma aplicação amigável é importante ter empatia e entender o contexto. Empatia nada mais é do que entender a fundo as necessidades do consumidor, colocando-se no lugar do dev e prevendo as possíveis dificuldades que ele terá durante o processo. Contexto diz respeito ao entendimento de como a integração via API se posiciona para entregar determinados resultados.
É importante levar em consideração esses dois aspectos e garantir que a sua API tenha um design que facilite o processo de integração. Lembre-se que o dev é uma ponte entre a sua plataforma e milhares de outras pessoas. Portanto, para garantir que o maior número de usuários se beneficie da sua solução, coloque as necessidades do desenvolvedor como prioridade.

O que caracteriza uma API com bom design

Contar com um bom design na sua API é fundamental para que ela seja amigável. Uma API bem desenhada costuma ter as seguintes características:

1- Facilmente compreensível

É muito mais fácil de se trabalhar com uma API bem desenhada. Em geral, suas operações podem ser facilmente memorizadas pelos desenvolvedores que a usam frequentemente.

2- Fácil de usar, mesmo com pouca documentação

Obviamente a sua API deve ser bem documentada. Porém, ela deve ter um design que seja intuitivo, a ponto de o desenvolvedor conseguir usá-la com pouca documentação.

3- Difícil de ser usada incorretamente

Realizar uma integração com uma API com bom design será um processo simples. Dessa maneira, escrever um código incorretamente é pouco provável.

4- Flexível

É difícil antecipar como os usuários vão aplicar os seus serviços. Como nem todas as plataformas dos clientes são consistentes é interessante ter um nível de flexibilidade com os inputs e outputs.

5- Segura

Segurança é um pré-requisito básico para uma API com bom design. A sua integração deve contar com autenticação antes da autorização de acesso, controle, cota de recurso e validação correta de parâmetros.

6- Boa documentação

Por fim, a sua API deve ter documentação de cada classe, método, parâmetro, interface, etc. Se ela tem um bom design, nada mais justo do que ser bem documentada.

6 princípios básicos para criar uma API com design amigável

Mensagens de erro claras

Crie mensagens de erro claras. O usuário precisa entender como utilizar a sua API. Porém, quando algo der errado na integração, deve entender o motivo. Em vez de simplesmente escrever mensagens como “parâmetro inválido”, ofereça uma explicação mais humana.
Uma mensagem de erro amigável pode conter diagnósticos e até link para documentações, com o objetivo de auxiliar o desenvolvedor.

Verbos HTTP – CRUD

Existem diversos verbos de ação HTTP disponíveis e pode ser que você tenha vontade de incorporá-los para tornar a sua API diferente das outras. Porém, o ideal neste caso é ser conservador e utilizar o bom e velho CRUD.
CRUD é o acrônimo para as quatro operações básicas: Create, Read, Update e Delete e significam:
CREATE — referente a criar ou adicionar novas entradas
READ — recuperar ou visualizar entradas existentes
UPDATE — atualizar ou editar entradas existentes
DELETE — remover entradas existentes
Pelo fato de ser bastante tradicional, é provável que os desenvolvedores esperem encontrar o CRUD na sua API. Portanto, misturar outros verbos de ações vai complicar o processo e fazer com que a sua integração não seja tão amigável.

Substantivos versus verbos

Sempre utilize substantivos (e não verbos) nas suas URLS quando estiver construindo uma API RESTful. Ao utilizar um verbo, ele se relaciona apenas a uma ação específica, trazendo pouca flexibilidade.
O ideal é utilizar substantivos e aproveitar os verbos de ação HTTP. Dessa maneira, você pode adicionar novas ações, de maneira organizada, a qualquer momento. Combinadas com hipermídias, os seus usuários podem tirar proveito das suas ações imediatamente.

Hipermídia

Nem todas as pessoas concordam com o uso de hipermídias em APIs RESTful. Porém, a verdade é que elas tornam a sua interface de programação de aplicações mais flexível. Com elas, é possível adicionar novas features na sua API e torná-las disponíveis instantaneamente para o usuário. Além disso, ela também permite que você mude alguns aspectos da sua API sem gerar incompatibilidade com versões anteriores.

Cabeçalhos Accept e Content-type

Uma maneira de garantir que a sua API seja flexível é desenhá-la pensando no futuro. A cada dia, novos formatos surgem e criar apenas pensando em XML e JSON pode torná-la obsoleta daqui alguns anos.
Portanto, na hora de construir uma nova API para o seu ERP, utilize cabeçalhos Accept e Content-type. Dessa maneira, quando você precisar adicionar novos formatos, todo o processo será mais simples.

Documentação

Por fim, a última ação para garantir que a sua API seja amigável é contar com uma boa documentação. Esse registro é fundamental para que os devs entendam como realizar a integração da sua API. Além disso, ela funciona como uma prévia do que eles vão encontrar na sua solução. Contar com uma documentação bem organizada e didática é fundamental para o sucesso do desenvolvedor e, consequentemente, o sucesso do seu ERP. Capriche neste tópico.