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çã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) |