Exemplo Básico de API

As APIs da Amil usam o protocolo de comunicação REST, essencialmente, e para iniciar seus primeiros passos em nosso ambiente, você pode combinar o método HTTP GET, POST, PUT, PATCH ou DELETE, com a URL para o serviço de API e o URI de consumo de um recurso para consultar, enviar dados, atualizar ou excluir, incluindo ainda, um ou mais cabeçalhos de solicitação HTTP.

A URL para o serviço de API é:

  • Teste: https://api-dev.servicos.grupoamil.com.br

  • Produção: https://api.servicos.grupoamil.com.br

Em muitos casos, você pode adicionar parâmetros de consulta em chamadas GET como filtrar, limitar o tamanho e classificar os dados nas respostas. É importante lembrar que, a maioria das chamadas GET, POST, PUT e PATCH exigem um corpo de solicitação JSON (request/body).

O exemplo a seguir, exibe a lista de bairros por plano

1 curl -v -X GET https://api-dev.servicos.grupoamil.com.br/api/RedeCredenciadaAtualizacoesBairro/1/SAUDE/SP/SAO%20PAULO/AMIL?_limit=25&_offset=0&_rowscount=250&_totalPages=10 \
2 -H "Content-Type: application/json"\
3 -H "Authorization: Bearer ACCESS-TOKEN"

Filtros, ordenação e paginação

O tema paginação é extremamente relevante do ponto de vista de saúde da estrutura de gateways de API, bem como do próximo endpoint que está operando o retorno das informações. Por isso, da importância em detalhar a estrutura que compõe o consumo desse tipo de API, são eles:

_limit: Quantidade de itens por página

  • mínimo: 1

  • máximo: 100

  • padrão: 25

  • exemplo: 10

_offset: Indica a primeira posição a ser retornada na resposta da consulta.

  • mínimo: 0

  • máximo: 50

  • exemplo: 40

_cursor: Indica o ID do último item da página. Em alguns casos, ainda usamos offset no lugar de cursor.

  • exemplo: 08ec231f6d9a43dda97d4b950c3393df

_filter: Indica se existe algum filtro a ser aplicado na resposta da consulta

  • formato: [Opções de Filtro: campo / operador / valor]

  • exemplo: cep>=099888777+bairro~leste

_orderby: Indica se tem alguma ordem (crescente ou decrescente) na resposta da consulta

  • formato: [Opções de Ordenação: campo / tipo]

  • exemplo: nome>+bairro<

Códigos de status HTTP

Os códigos de status HTTP, são números enviados pelo servidor da web como parte da resposta a uma requisição realizada por um cliente (como um navegador da web ou um aplicativo). O objetivo desses códigos está em fornecer os dados sobre o resultado da requisição e das informações sobre o sucesso, falha ou redirecionamento da requisição. Esses códigos estão divididos em cinco classes, conforme descrito abaixo:

1. Respostas Informativas (1xx): Esses códigos fornecem informações preliminares referente ao progresso da requisição. Eles não são comuns na maioria das interações e podem ser ignorados na maioria dos casos. Veja a seguir alguns exemplos:

  • 100 (Continue): Indica que o servidor recebeu a parte inicial da requisição e está pronto para receber o restante.

2. Respostas de Sucesso (2xx): Esses códigos indicam que a requisição foi recebida, entendida e aceita pelo servidor. Segue alguns exemplos:

  • 200 (OK): Indica que a requisição foi bem-sucedida e o servidor está retornando os dados solicitados.

  • 201 (Created): Usado após uma requisição POST bem-sucedida para indicar que um recurso foi criado.

  • 204 (No Content): Indica que a requisição foi bem-sucedida, porém não existem dados no body da resposta.

3. Respostas de Redirecionamento (3xx): Esses códigos indicam que o cliente precisa efetuar uma ação adicional para completar a requisição. O servidor está sinalizando ao cliente sobre a necessidade de um redirecionando para outro endereço. A seguir temos alguns exemplos:

  • 301 (Moved Permanently): Indica que o recurso solicitado foi movido permanentemente para outro endereço.

  • 302 (Found): Indica que o recurso foi encontrado temporariamente em um endereço diferente. O cliente deve usar a nova URL para a solicitação atual, mas pode continuar usando a URL original posteriormente.

  • 303 (See Other): Similar ao 302, mas indica que o cliente deve fazer uma solicitação GET separada para o novo endereço.

4. Respostas de Erro do Cliente (4xx): Esses códigos indicam que a requisição do cliente gerou algum erro no lado do cliente. Alguns exemplos são listados a seguir:

  • 400 (Bad Request): Indica que a requisição do cliente é inválida ou faltando algo.

  • 401 (Unauthorized): Indica que o cliente não forneceu as credenciais de autenticação válidas ou a autenticação falhou.

  • 403 (Forbidden): Indica que o cliente não tem permissão para acessar o recurso requisitado.

5. Respostas de Erro do Servidor (5xx): Esses códigos indicam que o servidor encontrou um problema ao processar a requisição do cliente. Esse tipo de falha indica um defeito no lado do servidor. A seguir foram listados alguns exemplos:

  • 500 (Internal Server Error): Indica um erro genérico do servidor que não pode ser classificado em nenhuma categoria específica.

  • 502 (Bad Gateway): Indica que o servidor atuou como um gateway ou proxy e recebeu uma resposta inválida do servidor principal.

  • 503 (Service Unavailable): Indica que o servidor não está disponível para processar a requisição. Isso pode ser devido à sobrecarga ou manutenção temporária.

Conclusão

Uma melhor compreensão dos princípios e práticas relacionados a APIs RESTful permitem aproveitar todo o potencial dessa tecnologia para atender às necessidades do seu projeto. Além disso, compreender os códigos de resposta HTTP é fundamental para solucionar problemas, depurar requisições e garantir que os aplicativos e serviços web funcionem corretamente.