PORTAL DO DESENVOLVEDOR

Visão Geral

Todos os serviços disponibilizados através da API utilizam a tecnologia REST (Representational State Transfer), uma arquitetura para a disponibilização de recursos através de sistemas distribuídos, popularmente utilizado sobre HTTP. Abaixo podemos verificar exemplos de como os serviços são formados:


Sendo que:

HOSTNAME

Endereço principal dos serviços

VERSÃO DA API

Versão do serviço que está sendo consumido

RECURSO RAIZ

Nome do serviço

A partir do Recurso Raiz, podemos acessar as principais operações do serviço. Como a API da Transparência Brasil disponibiliza apenas dados para consulta, é utilizado somente o método HTTP GET

HTTP 1.1

O protocolo padrão para comunicação com as APIs é o HTTP versão 1.1. Para maiores informações sobre esse protocolo, consulte: http://www.w3.org/Protocols/rfc2616/rfc2616.html http://www.ietf.org/rfc/rfc2616.txt

UTF-8

O Charset padrão para chamadas às APIs é o UTF-8. Para maiores informações sobre essa codificação, consulte: https://tools.ietf.org/html/rfc3629   

JSON

JSON (JavaScript Object Notation) é um padrão para descrição de dados para intercâmbio entre sistemas e é mais simples e mais leve que o XML. Por padrão toda a API trafega JSON, tanto para receber informações quanto no retorno.

Exemplo de response do recurso /estados:

        [
          {
            "EstadoId": "1",
            "sigla": "RJ",
            "nome": "Rio de Janeiro"
          },
            {
            "EstadoId": "2",
            "sigla": "SP",
            "nome": "São Paulo"
          }
        ]

Paginação

Durante a exibição do resultado de alguns métodos da API é necessário o uso de parâmetros de paginação. Para paginar resultados é necessário utilizar dois parâmetros na própria Query String _offset e _limit, conforme exemplos abaixo:

https://api.transparencia.org.br/api/v1/candidatos?_offset=0&_limit=100

Como resultado deverá retornar uma lista contendo 100 objetos a partir do primeiro objeto da lista.

_offset: Indica a posição inicial da consulta. Ou seja, 100, indica o primeiro registro trazido deve estar na posição 100.

_limit: Indica a quantidade de registros que a consulta irá retornar.

Observação:

O índice das listagems inicia em 0 (zero). Ou seja para uma consulta com os 10 primeiros itens de uma lista (_offset=0 e _limit=10), os índices serão de zero (0) a nove (9).

Alguns recursos estão com paginação default, sendo assim,  um GET sem nenhum parametro de filtro não retornará muitos registros resultando em uma baixa performance.


Página Autenticação:

O tráfego de informações deve feito através de protocolo HTTPS, unicamente, sendo que para chamadas a recursos que não sejam feitas por intermédio deste protocolo, o conteúdo trafegado fica sob responsabilidade do Desenvolvedor.

Todas as chamadas deverão conter, além dos campos da requisição, um campo no cabeçalho para a identificação de segurança. O nome desse campo é:

Application Token (ou App-Token): Token que identifica a Aplicação que está efetuando a chamada aos recursos disponibilizados através da API.

Uma vez que você tenha se inscrito no portal, basta clicar no link “APPS” no cabeçalho.

Daí, basta registrar um novo App conforme imagem abaixo:

 

Depois de preencher os dados, você obterá uma tela como a abaixo. Basta copiar o App-Token e usá-lo em todas as chamadas das APIs:

Para testar se seu App-Token está válido e funcional, basta acessar o API Browser no menu Documentação. Escolher algum recursos e fazer o “Try it out!” conforme a imagem abaixo: