Introdução à API

Conceitos Básicos

O que é uma API?
O nome origina-se de “Application Programming Interface”, que em português significa “Interface de Programação de Aplicativos”. Na prática, trata-se de um meio pelo qual uma empresa de software pode permitir a outros desenvolvedores criarem produtos associados a seu serviço.

RESTFul API
Nossas APIs são RESTFul (Representational State Tranfer), o que significa que elas não armazenam estado, portanto cada chamada é completamente independente das demais. Uma API Rest, na prática, detém vantagens sobre as metodologias definidas pelo procotolo HTTP, como por exemplo, a utilização dos verbos já especificados para a representação das ações a serem executadas sobre os recursos. Exemplos: utilização do método GET para consulta de informações, o método POST para criação de novos recursos, DELETE para remoção, etc.

Na prática a API é acessível através de uma URI composta dos seguintes elementos: https://<ambiente>/<produto>/<versão>/<recursos>/<parâmetros>

Sendo que o protocolo utilizado é sempre o “https” devido a criptografia necessária para a transferência de dados de forma segura. Os demais elementos são descritos em detalhes abaixo:

  • produto: representa o produto ANBIMA exposto através da API em questão
  • versão: representa a versão da API em questão
  • recursos: identificam as informações que se esperam obter ao chamar determinado serviço (no contexto desta API, trata-se dos pacotes e itens , os quais contém as informações dos índices)

Formato do conteúdo de resposta das APIs da ANBIMA: Como padrão, todas as respostas são no formato JSON (JavaScript Object Notation) - um padrão aberto que considera texto legível a humanos para transmissão de dados, os quais consistem de pares “atributo/valor”. Para mais informações a respeito deste formato, é possível acessar a seguinte referência:

https://www.json.org/json-pt.html

No entanto, para algumas APIs é possível enviar um header para obter o formato em XML

Tecnologias e Padrões

REST

Arquitetura para a disponibilização de recursos através de sistemas distribuídos, popularmente utilizado sobre o protocolo HTTP. Mais detalhes em: https://www.w3.org/2001/sw/wiki/REST.

JSON

Padrão para descrição de dados utilizado para intercâmbio de informações entre sistemas, é mais simples e leve do que algumas alternativas de mercado, como XML. Mais detalhes em: https://www.w3.org/TR/html-json-forms/#introduction.

HTTP 1.1

Protocolo de transporte padrão, amplamente utilizado. Mais detalhes em: http://www.w3.org/Protocols/rfc2616/rfc2616.html ou http://www.ietf.org/rfc/rfc2616.txt.

UTF-8

Conjunto de caracteres padrão para comunicação entre sistemas distribuidos. Mais detalhes em: https://www.w3.org/International/questions/qa-choosing-encodings.

ISO-8601

Padrão de formato específico para dados do tipo date e hora.

							
Padrão: YYYY-MM-DDThh:mm:ss.sTZD
Exemplo: 2013-06-28T08:54:00.000-03:00
							
						

Endpoints

Existem apenas dois endpoints para acesso às nossas APIs, um de Produção e outro de Sandbox. Enquanto sua aplicação estiver sendo desenvolvida utilize sempre o endpoint de Sandbox e só altere para o de Produção quando tiver realizado toda parte de integração de sua aplicação. Os endpoins ANBIMA para acesso aos ambientes seguem abaixo:

URL de Produção URL de Sandbox
https://api.anbima.com.br https://api-sandbox.anbima.com.br

Observação importante: Não se esqueça de incluir a versão da API antes do recurso, por exemplo: /api/v1, para a versão 1 da API.

Códigos de Status HTTP

Código de Status Descrição
1xx Informativo – Não utilizado para APIs
2xx Sucesso
3xx Redirecionamento
4xx Erro de Cliente
5xx Erro de Servidor

Principais variações do Código de Status 2xx:

Código de Status Descrição
200 Ok
201 Created
202 Accepted
204 No Content

Principais variações do Código de Status 4xx:

Código de Status Descrição
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method not Allowed
412 Precondition Failed
413 Request Entity Too large
415 Unsupported Media Type
422 Unprocessable Entity
429 Too many requests

Principais variações do Código de Status 5xx:

Código de Status Descrição
500 Internal Server Error
502 Bad Gateway
504 Gateway Timeout

Padrões de Localização

Dados de Formato de Campos e Região:

Calendário: Calendário Gregoriano
País: Brasil
Moeda: Real
Primeiro dia da semana: Domingo
Formato data: YYYY-MM-DD (ex: 2021-06-14)
Separador milhar: Ponto (ex: 1.000)
Separador decimal: Vírgula (ex: 0,57)