Introdução à API

O que é uma API?

O nome origina-se de “Application Programming Interface”, que em português significa “Interface de Programação de Aplicações”. Através de APIs, aplicações podem se comunicar umas com as outras sem intervenção dos usuários. Elas funcionam através da comunicação de diversos códigos, definindo comportamentos específicos de determinado objeto em uma interface. 

De modo geral, a API é composta de uma série de funções acessíveis somente por meio de programação.

APIs RESTFul

As nossas APIs adotam a especificação RESTFul (Representational State Tranfer), o que significa que elas não armazenam estado. Sendo assim, cada chamada é completamente independente das demais. Uma API REST, na prática, detém vantagens sobre as metodologias definidas pelo protocolo 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

Como padrão, todas as respostas das APIs da ANBIMA 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çãoURL 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 StatusDescrição
1xxInformativo – Não utilizado para APIs
2xxSucesso
3xxRedirecionamento
4xxErro de Cliente
5xxErro de Servidor

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

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

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

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

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

Código de StatusDescrição
500Internal Server Error
502Bad Gateway
504Gateway 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)