Como começar a utilizar a API REST da PGI



A API REST da PGI oferece a facilidade de se obter e escrever dados da aplicação PGI através de requisições no padrão REST.

A API é de livre acesso para requisições de leitura, enquanto nas requisições de escrita é obrigatório a existência de um cadastro ativo na PGI. Este cadastro é necessário pois tais funcionalidades de escrita registram em log a atividade de cada usuário por meio de um 'token', associado àquele usuário em questão.

Cadastro na PGI:

Caso não possua um cadastro na PGI, é possível realiza-lo neste link.

Basta preencher o cadastro e clicar em 'enviar'.


Caso já possua um cadastro na PGI, é possível se logar neste link.

Basta preencher o cadastro e clicar em 'enviar'.





Requisitando Token de identificação:


Toda requisição de escrita necessita de um Token Identificador de acesso à API, que deve ser passado no Header da requisição. Toda requisição recebida pela API é guardada em um log de acesso junto do Token.

Para requisitar um token novo é necessário estar logado em seu cadastro na PGI e clicar na aba "Administração" e logo em seguida clicar no link "Usuário".

Geração de Token

Clique no icone de token para iniciar o processo de geração de um novo token. Se tudo ocorrer corretamente, seu token estará visível na tela e será enviado e-mail do usuário cadastrado.




Informações relevantes:

Metadados:

Antes de realizar qualquer tipo de requisição na API, é importante ter conhecimento dos metadados de cada entidade da PGI. Há uma documentação disponível neste link que contém tabelas com informações de referência sobre os metadados.

- Requisições:

A API suporta requisições e respostas no formato JSON e XML. Para especificar o formato da requisição/resposta deve-se acessar a url com a extensão em questão (.json ou .xml). Se nenhum Header for passado, especificando o tipo de formato da requisição, o padrão será XML.

Nas requisições de escrita existem campos que são obrigatórios, geralmente campos não-nulos do banco. Na documentação da API é possível ver a lista de quais parâmetros são aceitos por cada requisição, assim como seu tipo e obrigatoriedade.

É possível passar o valor de um campo não-obrigatório como "null", porém ele não será considerado no momento da persistência no banco. Portanto, se o usuário passar um parâmetro não-obrigatório com valor "null" o resultado terá o mesmo efeito de omiti-lo da requisição.


-Mensagem de erros:

A API REST da PGI possui um sistema de tratamento de erros que sempre retorna uma resposta com um código do erro, uma mensagem explicando o erro e uma sugestão de solução para o erro.

Exemplo de um erro gerado em uma requisição JSON:
{"code":401,"message":"Não existe Usuario com o token: 1234567890987654321.","suggestion":"Verifique se o token esta correto."}







O fluxo de utilização padrão da API se dá em 6 simples passos:

1) Criação de Grupo de Informações

curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X POST -d '{"grupoinformacao":{"nome": "GrupoInformacao - 1", "descricao": "Descricao grupo informacao"}, "palavrasChave": [{"nome": "palavraChave(1)"},{ "nome": "palavraChave(2}"}]}' http://dev.api.pgi.gov.br/api/1/grupo



2) Criação de Série Histórica associada ao grupo criado anteriormente:

(Suponha que o ID do grupo criado é 662)
curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X POST -d '{"seriehistorica":{"nome": "SerieHIstoricaTeste - 1", "nome_estendido": "Serie Historica de Teste numero 1", "descricao":"descricao-teste", "formatacao":"2", "url_origem":"http://www.teste.com/", "disponibilizacao":6, "estado":1, "fonte_gestora":246, "fonte_provedora": 354, "grupo_informacao":662, "base_territorial":3, "periodicidade":1, "publicacao": 2, "orgao_primeiro_escalao": 21, "inicio":2003, "final": 2014, "publicacao": 1, "multiplicador":1, "aditividade": 1, "tempo_aditividade": 1, "portal_dados_abertos": false }, "valores":[{"valor":1234, "ano":2001, "brasil_ibge": 1}, {"valor":"1111", "ano": 2011, "brasil_ibge": 1}]}' http://dev.api.pgi.gov.br/api/1/serie



3) Editar Série Histórica criada:

(Suponha que o ID da Série criada é 24)
curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X PUT -d '{"seriehistorica":{"nome": "EDITADO", "nome_estendido": "EDITADO", "descricao":"EDITADO"}}' http://dev.api.pgi.gov.br/api/1/serie/24




4) Obter a Série Histórica criada:

(Suponha que o ID da Série criada e editada é 24)
curl -H "Content-Type: application/json" -X GET http://dev.api.pgi.gov.br/api/1/serie/24
ou
curl -X GET http://dev.api.pgi.gov.br/api/1/serie/24.json  (Atenção para o formato !)




5) Remover a Série Histórica criada:

(Suponha que o ID da Série obtida é 24)
curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X DELETE http://dev.api.pgi.gov.br/api/1/serie/24




6) Remover Grupo de Informações criado

(Suponha que o ID do grupo a ser removido é 662)
curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X DELETE http://dev.api.pgi.gov.br/api/1/grupo/662







Árvores Temáticas

Abaixo encontram-se os métodos referentes a entidade Árvore Temática:

1) Criação de uma Árvore Temática com itens associados a ela:

curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X POST -d '{"tematica":{"nome": "ArvoreTematica - teste", "niveis":1, "ativo":1, "ordem_apresentacao":1010, "fonte_dados":60, "tipo_grupo_informacao": 1}, "itens": [{ "nome": "item - teste", "nivel": 1, "ordemApresentacao": 1010, "localInstitucional": 0, "serieHistorica": 2681}, { "nome": "[2]item - teste", "nivel": 1, "ordemApresentacao": 1010, "localInstitucional": "1", "serieHistorica": 2681}] }' http://dev.api.pgi.gov.br/api/1/tematica -vvv



2) Visuaização da Árvore Temática inserida

(Suponha que o ID do árvore criada é 58)
 curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X GET  http://dev.api.pgi.gov.br/api/1/tematica/58.json
*Token não é obrigatório
*Este métdo retorna os itens pertencentes à Temática específicada, mas não retorna as Séries Históricas associadas à cada item.


3) Edição de uma Árvore Temática com itens associados a ela:

curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X PUT -d '{"tematica":{"nome": "ArvoreTematica - testeEDITADO", "niveis":1, "ativo":1, "ordem_apresentacao":11, "fonte_dados":60, "tipo_grupo_informacao": 1}}' http://dev.api.pgi.gov.br/api/1/tematica/40 -vvv
*Este método está considerando "absolutamente" os Itens passados. Se nenhum item for passado na edição desta Temática, significa que o atributo Itens será zerado.


4) Remoção de uma Árvore Temática:

(Suponha que o ID da temática a ser removida é 2)
curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X DELETE http://dev.api.pgi.gov.br/api/1/tematica/2 -vvv


5) Itens relacionados a Temática

5.1) Inserção de um item em uma Temática:

(Suponha que o ID da temática associada é 58)
curl -H "Content-Type: application/json" -H  "Token: 012345678909876543210" -X POST -d '{"itens": [{ "nome": "item - teste", "nivel": 1, "ordemApresentacao": 1111, "localInstitucional": 0, "serieHistorica": 2681, "tematica": 58}] }' http://dev.api.pgi.gov.br/api/1/item -vvv



5.2) Edição de um item específico:

(Suponha que o ID do item a ser editado é 12345)
curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X PUT -d '{"itens": [{ "nome": "AAAAA - testeEDITADO", "nivel": 1, "ordemApresentacao": 1111, "localInstitucional": 0, "serieHistorica": 1, "tematica": 37}] }' http://dev.api.pgi.gov.br/api/1/item/12345 -vvv

*Note que alteramos a temática associada à este item.




5.3) Remoção de um item específico:

(Suponha que o ID do item a ser removido é 12345)
curl -H "Content-Type: application/json" -H "Token: 012345678909876543210" -X DELETE  http://dev.api.pgi.gov.br/api/1/item/12345.json -vvv