Em quais desses testes a sua API passa?

 

Interfaces de Programação de Aplicativos (APIs) permitem que desenvolvedores utilizem dados e funcionalidades de outros sistemas sem a necessidade de conhecer em detalhe a implementação dos mesmos.

A primeira coisa que um desenvolvedor deve procurar quando vai utilizar uma API é a documentação. Nela deve ser possível encontrar informações sobre como utilizar os métodos disponibilizados, quais são esses métodos e como tratar possíveis erros na sua utilização.

twitterapi A documentação é, portanto, uma parte muito importante da API, especialmente se ela for pública, mais ainda se ela for comercializável, e merece nossa atenção. Assim como uma interface web ou mobile, a API precisa ser clara e intuitiva e sua principal apresentação é a documentação.

Entretanto, não adianta esmerar-se na documentação se a arquitetura foi mal pensada. Arquitetura e documentação são características que andam lado a lado. Vamos falar um pouco sobre boas práticas em uma API que podemos verificar através da documentação.

 

Exemplo: Sistema Veterinário

Pare agora rapidamente para pensar em um sistema veterinário e algumas das ações que seriam importantes nesse sistema. … Pensou? Como seriam as URLs de acesso a essas funções? Algumas que passaram pela minha cabeça:

/listarAnimais

/cadastrarAnimal

/listarGatos

/listarCachorros

/marcarProcedimento

/cadastrarDono

/encaminharAnimalParaMedico

E tantos outros exemplos. O problema é que essa é uma lista gigante e nada intuitiva. Eis então a primeira boa prática:

1. Use os verbos HTTP para lidar com objetos e coleções de objetos e substantivos para descrevê-los.

Os principais verbos HTTP são: POST, GET, PUT e DELETE e equivalem às ações que aprendemos como CRUD (Create-Read-Update-Delete). Como utilizá-los?

Requisição: POST /animais

Resultado esperado: Criar um novo animal com base nos dados enviados.


Requisição: GET /animais

Resultado esperado: Uma lista de animais do sistema.


Requisição: PUT /animais

Resultado esperado: Atualização em massa dos animais.


Requisição: DELETE /animais

Resultado esperado: Apagar todos os animais.

 

E se ao invés da coleção, a ideia for trabalhar com um objeto apenas?

Requisição: POST /animais/111

Resultado esperado: Erro


Requisição: GET /animais/111

Resultado esperado: Detalhes do animal 111


Requisição: PUT /animais/111

Resultado esperado: Atualização do animal 111


Requisição: DELETE /animais/111

Resultado esperado: Apagar o animal 111

 

Note que os verbos cadastrar, listar, atualizar e apagar foram sustituidos por POST, GET, PUT e DELETE.

 

2. Simplifique os níveis de associações e use querystring para filtros

É possível perceber relações entre entidades através da URL. No sistema do veterinário, cada animal pertence a um dono, que também é uma entidade no sistema, pois é necessário saber algumas informações sobre ele como nome e contato.

 

Então como saber quais são os animais do dono 222?

  • GET /donos/222/animais/

E para registrar um novo animal para o dono 222?

  • POST /donos/222/animais

 

Aqui o cuidado é com não criar URLs com infinitos níveis e respeitar a ordem:

  • /recurso/identificador/sub-recurso

 

E qual a maneira mais fácil de encontrar o animal 2 que pertence ao dono 123?

  • GET /animais/2

Afinal, independente de quem seja o dono do animal 2 possui, ele ainda é o animal 2.

 

É importante respeitar essa ordem e ter cuidado com a semântica dos níveis na URL. Lembre-se: queremos que as APIs sejam o mais fácil possível de usar, assim como qualquer outra interface.

Além das relações acima, também é preciso lidar com peculiaridades dos objetos como estados e características. Para isso, podemos usar filtros no método GET. Uma das maneiras é por uma interrogação no fim da URL e formar uma querystring.

9549595208_89169758fe_m

Fonte: Flickr

 

Então como ficaria a construção da URL para buscar todos os poodles?

  • GET /animais?raca=poodle

E se eu quisesse todos os poodles brancos?

  • GET /animais?raca=poodle&cor=branco

Vale lembrar que querystrings são usadas apenas com o método GET.

 

3. Tratamento de erros

Como comentei no começo do post, quando utilizamos uma API não sabemos os seus detalhes de implementação. É importante que os erros retornados pela API sejam então informativos para que possamos atuar sobre eles. Veja aqui a lista de códigos http.

 

É preciso implementar todos eles?

Definitivamente não. Nem todo mundo sabe todos esses erros de cabeça e se a API é intuitiva, isso também significa que os desenvolvedores não tem que sair por ai pesquisando o que quer dizer o código. A prática mais comum é ter um pequeno conjunto de códigos implementados e direcionar os problemas para o código que melhor representa a situação, adicionando uma mensagem sempre que necessário.

Fonte: Flickr @girlie_mac

Fonte: Flickr @girlie_mac

 

Os principais grupos de erros HTTP são:

2xx Sucesso, sendo o mais utilizado: 200 (OK)

4xx Erros de cliente, sendo os mais comuns: 400 (Bad request) e 404 (Not found)

5xx Erros no lado do servidor, como exemplo desse grupo, claro, o nosso companheiro erro 500 (Internal server error).

 

Imagine agora a seguinte chamada no sistema veterinário:

  • GET /search?q=lulu
  • Código retornado: 200
  • {“message”: “#830 O recursos requisitado não existe:lulu”}

Para melhorar esse retorno, a primeira coisa a fazer é atribuir o código correto, nesse caso poderia ser 404. Mas só isso já deixa a mensagem clara? O que é #830? E como eu posso resolver esse problema? Uma solução mais elegante seria:

  • Código retornado: 404
  • {“developerMessage”: “No results found”, “userMessage”: “Não foram encontrados resultados para lulu. Verifique se o termo de pesquisa está correto.”, “errorCode”:830,”moreInfo”:”http://minha.api.com/errors/830”}

No segundo caso temos uma mensagem interna que será tratada pelo desenvolvedor, idealmente escrita em inglês, especialmente se há a possibilidade de qualquer desenvolvedor que não fala português utilizar a sua API, uma mensagem para o usuário final, o código do erro e um link para maiores informações sobre o erro e como corrigi-lo.


Esse foi o meu primeiro post no QALab e também o primeiro post sobre APIs de uma série que estão por vir. Quer saber mais sobre APIs e como testá-las? Junte-se a nós no curso Introdução à Validação de APIs Web.

 

E para mostrar que você entendeu mesmo, que tal responder a pergunta abaixo?

No item 1, eu mencionei que a chamada abaixo geraria um erro:

  • POST /animais/111

Qual seria o código mais adequado para esse erro?

 

Aguardo as respostas aqui no blog e em breve traremos mais dicas sobre APIs.

3 thoughts on “Em quais desses testes a sua API passa?

Deixe uma resposta

O seu endereço de email não será publicado. Campos obrigatórios marcados com *

*