Dados Abertos - IFFAR
Documentação da API de Dados Abertos do IFFAR
O acesso aos dados abertos é feito através de nossa API, que consiste em endereços de internet URL (Uniform Resource Locator) prontos para serem aproveitados por outros aplicativos. É possível também filtrar as consultas através da informação de parâmetros, com os dados sendo disponibilizados nos formatos JSON, XML, CSV e HTML.
Para acessar os dados abertos disponibilizados pelo IFFAR, é necessário primeiramente conhecer o formato da URL básica, assim como a descrição das informações e dos seus parâmetros.
Formato da URL:
https://dados.iffarroupilha.edu.br/api/v1/<recurso>.<formato>?<campo1>=<valor1>&<campo2>=<valor2>
Para utilizar a URL básica acima, duas informações são obrigatórias: <recurso> e <formato>. O <recurso> indica qual informação você deseja obter e o <formato> define sua preferência em receber a resposta (JSON, XML, CSV ou HTML). Já os parâmetros <campoN> e <valorN> são utilizados para filtrar os registros retornados pelos recursos.
Disponibilizamos abaixo, alguns exemplos de consultas diretas na API do Dados Abertos do IFFAR para facilitar seu entedimento, caso ainda não tenha familiaridade com qualquer API de consulta.
Exemplo 1: Para listar todos os cursos do IFFAR do nível graduação, no formato JSON:
https://dados.iffarroupilha.edu.br/api/v1/cursos.json?nivel=G
Exemplo 2: Para listar todos os servidores do IFFAR da categoria docente com formação de doutorado, no formato XML:
https://dados.iffarroupilha.edu.br/api/v1/servidores.xml?id_categoria=1&id_formacao=27
Exemplo 3: Para listar todos os componentes curriculares do IFFAR do nível graduação que tenham carga horária teórica de 80 horas, no formato HTML:
https://dados.iffarroupilha.edu.br/api/v1/componentes-curriculares.html?nivel=G&ch_teorico=80
Exemplo 4: Para listar de todas as unidades organizacionais do IFFAR, no formato CSV:
https://dados.iffarroupilha.edu.br/api/v1/unidades-organizacionais.csv
Por questões de performance, recursos marcados com um asterisco ao lado do seu nome, possuem um limite de 10.000 registros para o retorno das consultas. Nestas situações, caso deseje visualizar os demais registros desses recursos, utilize o parâmetro offset disponível nos mesmos. Logo abaixo, há dois exemplos de uso do parâmetro offset para melhor entendimento.
Exemplo 1: Para listar os primeiros 10.000 bens móveis do patrimônio do IFFAR, no formato HTML:
https://dados.iffarroupilha.edu.br/api/v1/bens-moveis.html
Exemplo 2: Para listar os próximos 10.000 bens móveis do patrimônio do IFFAR, a partir do registro 10.001, no formato HTML:
https://dados.iffarroupilha.edu.br/api/v1/bens-moveis.html?offset=10000
Para verificar quais os recursos estão disponíveis, assim como os parâmetros para cada recurso e se existem parâmetros obrígatórios nos mesmos, consulte a documentação em Recursos da API.
Em um primeiro momento, a API de Dados Abertos do IFFAR oferece quatro formatos de resposta para as consultas: JSON, XML, CSV e HTML.
O formato JSON é um modelo leve e simples para armazenamento e intercâmbio de dados no formato texto que tem sido muito utilizado como alternativa ao XML, por ser muito mais simples de se trabalhar e estruturar informações. É o formato padrão que deve ser retornado nas consultas pela API, caso o usuário deseje aproveitar os dados em outros aplicativos.
Resposta JSON:
{
"info": {
"count": /* número de registros da consulta */
},
"data": [
{
/* registros retornados da consulta */
}
]
}
O formato XML é uma linguagem de marcação assim como o HTML, mas extensível para descrever os dados que representa. Tem sido cada vez menos utilizado em novas aplicações, pois os desenvolvedores dão preferência ao formato JSON, na maioria das vezes por ser mais simples de se trabalhar. Entretanto, o formato XML ainda é amplamente utilizado na troca de dados entre aplicativos na web.
Resposta XML:
<dataset>
<info>
<count><!-- número de registros da consulta --></count>
</info>
<data>
<!-- registros retornados da consulta -->
</data>
</dataset>
O formato CSV é um formato para armazenamento de dados tabulares em texto. A codificação é muito simples: cada linha do arquivo representa uma linha na tabela, onde a primeira linha contém o nome dos campos retornados e as demais o conteúdo retornado, além disso, as colunas são separadas por vírgula, e campos que podem conter vírgula devem ser delimitados por aspas.
O formato HTML não é um formato de Dados Abertos de fato, as consultas em formato HTML estão disponíveis com o principal intuito de facilitar a visualização dos dados retornados por qualquer pessoa. As respostas em HTML serão apresentadas em forma de tabelas formatadas, onde a primeira linha contém o nome dos campos retornado e as demais o conteúdo retornado.