Documentação
Sobre
Esta seção descreve instruções do uso da API de Sistemas para desenvolvedores que desejam utiliza-la na criação de aplicações para qualquer plataforma desejada. Abaixo serão detalhados os processos de concessão de acesso, autenticação, padrões e utilização dos serviços existentes.
Ambientes (Testes e Produção)
A API dispõe de um ambiente de testes que deverá ser usado durante o processo de desenvolvimento e o ambiente de produção que deverá ser usado após a homologação da sua aplicação.
Testes
A URL base para o ambiente de testes da api:
https://api.info.ufrn.br
Atenção! Para realizar a autenticação no ambiente de testes da API, deve-se utilizar a seguinte URL base:
https://autenticacao.info.ufrn.br
Produção
A URL base para o ambiente de produção da api:
https://api.ufrn.br
Atenção! Para realizar a autenticação no ambiente de produção da API, deve-se utilizar a seguinte URL base:
https://autenticacao.ufrn.br
Cadastro de Aplicação
Atualmente, o cadastro da aplicação está sendo realizado por meio de uma solicitação via formulário. Após a solicitação, você receberá por email, em até 48 horas, suas credenciais de acesso à API.Sistemas. Serão enviados no email de resposta o client-id, client-secret e x-api-key da sua aplicação.
Obs.: Inicialmente, você deverá solicitar as credenciais do ambiente de testes da API, através do formulário deste link. Após o desenvolvimento e validação da sua aplicação em testes, será necessário solicitar, através do preenchimento do formulário deste link, novas credenciais para o ambiente de produção.
Alerta! Não será possível acessar a API no ambiente de testes com as credenciais de produção, como também não será possível o caso inverso.

Primeiros Passos
Passo 1
Gostou da API de Sistemas da UFRN e quer utilizá-la? Faça agora o seu cadastro clicando neste link.
Passo 2
De posse do seu client-id, client-secret e x-api-key será possível consumir os serviços da API de Sistemas.
Antes de consumir qualquer serviço, será necessário se autenticar na API para gerar o acess-token. Existem duas formas de se autenticar, a escolha de uma delas dependerá do tipo de sua aplicação. Clique aqui para ver as formas de autenticações disponíveis.
Passo 3
Utilizando o acess-token gerado no passo anterior e o x-api-key, será possível consumir os serviços disponíveis na API de Sistemas. Para isso, é necessário passar esses parâmetros no cabeçaho da requisição. Conforme exemplo abaixo:
curl -H 'Authorization:bearer ACESS-TOKEN' -H 'x-api-key: X-API-KEY' "URL-BASE/discente/VERSAO/discentes?nome-discente=JOAO
A resposta não foi a esperarada? Veja os possíveis códigos HTTP retornados pela API de Sistemas.
A nossa equipe disponibilizou exemplos deste passo em diversas linguaguens de programação, clique aqui e confira alguns desses exemplos.
Padrões da API
Formato dos Dados
Na troca de mensagens com a API de Sistemas, será utilizado o padrão JSON (JavaScript Object Notation). Por isso, não é preciso fornecer o tipo de retorno desejado, toda requisição apresentará a seguinte informação no cabeçalho HTTP.
# Headers do formato de dados
date: Fri, 20 Oct 2017 16:14:54 GMT
content-type: application/json;charset=UTF-8
Encoding Utilizado
Os dados enviados (via POST ou PUT) devem estar de acordo com o charset UTF-8.
Por padrão todos os retornos via GET respondem com charset UTF-8.
Caso seja utilizado um encoding diferente, será retornado um erro de tipo de dados não suportados (HTTP Status 415).
Paginação
A API de Sistemas oferece a funcionalidade de paginação dos resultados obtidos nas consultas. Para utilizá-la, basta especificar a faixa de registros a serem retornados pela API fazendo uso dos parâmetros:
- offset: indica o salto de registros que deverá ser realizado. Caso não seja especificado, os primeiros registros da consulta serão retornados. (valor padrão 0);
- limit: indica a quantidade de registros que deverão ser retornados. O limit inferior é 0 (caso não seja informado, por padrão, serão retornados 20 registros) e o limite superior é de 100 registros.
No exemplo abaixo, a API de Sistemas retornará os cursos de graduação no intervalo de 21-40:
GET URL-BASE/curso/VERSAO/cursos?nivel=G&limit=20&offset=20
Para obter o número total de registros e a quantidade de páginas (baseado no offset e limit passados) será necessário passar no cabeçalho da requisição o parâmetro "paginado" com os valores "true", "sim" ou "yes".
Atenção! É recomendado solicitar esses parâmetros apenas quando necessário (por exemplo, na primeira requisição - caso seja realmente necessário), pois o uso desse mecânismo implica em retornos um pouco mais demorados.
Filtros
Parâmetros na Query
A API de Sistemas oferece a funcionalidade de filtrar os resultados obtidos nas consultas de pedidos e produtos fazendo uso de query params:
GET URL-BASE/discente/VERSAO/discentes?nivel=G
Na consulta do exemplo acima, serão retornados os 20 primeiros discentes de graduação. Por padrão, sempre que for feito o uso de query param o resultado será uma lista com os dados encontrados.
Os campos disponíveis para filtragem são descritos nas documentações dos serviços da API.
Parâmetros no Path
A API de Sistemas oferece a funcionalidade de filtrar os resultados obtidos nas consultas de pedidos e produtos fazendo uso de path param:
GET URL-BASE/discente/VERSAO/discentes/23232
Na consulta do exemplo acima, será retornado o discente do identificador passado como path na URL. Por padrão, sempre que for feito o uso de path param no final da URL, o resultado será sempre um elemento.
Códigos de Retorno (HTTP status)
A API de Sistemas utiliza o grupo padrão dos status HTTP para indicar se uma requisição teve sucesso ou não. No geral:
- Códigos HTTP 2xx: indicam que a requisição foi realizada com sucesso;
- Códigos HTTP 4xx: indicam que a requisição contém alguma informação incorreta - dados de acesso incorretos, ausência de um campo obrigatório, campos incorretos, etc;
- Códigos HTTP 5xx: indicam algum erro nos servidores da API de Sistemas.
Limite de Requisições
Para garantir o bom desempenho da API, as aplicações serão submetidas a um limite de requisições (throttling). O limite de requisições na API de Sistemas é por aplicação, cada aplicação tem um limite de 5.000 requisições por hora. Caso esse limite seja ultrapassado, será retornado erro HTTP 429.
É importante ressaltar que, ao receber o primeiro erro HTTP 429, a sua aplicação deverá aguardar uma nova janela de requisições para não incorrer no mesmo erro.
Aplicações Conectadas
Exemplos
Abaixo encontram-se os links do github de alguns exemplos de autenticação e consumo de serviços utilizando liguagens distintas:
Exemplos em Java
https://github.com/sti-ufrn?language=java
Exemplos em PHP
https://github.com/sti-ufrn?language=php
Exemplos em JavaScript
https://github.com/sti-ufrn?language=javascript
Exemplos em Python
https://github.com/sti-ufrn?language=python
Exemplos em Swift
https://github.com/sti-ufrn?language=swift