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

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.

Client Credentials

Esse fluxo foi implementado para ser usado por aplicações que queiram acessar os dados públicos dos sistemas da STI, tais como eventos, notícias, telefones, entre outros. Deste modo, aplicações que possuem esse fim devem seguir os passos abaixo:

1. A aplicação deverá realizar uma requisição POST ao authorization server, passando o client_id, client_secret e grant_type como QueryParam: Ex.:

    URL-BASE/authz-server/oauth/token?client_id=AppId&client_secret=AppSecret&grant_type=client_credentials 

2. O authorization server retorna à aplicação um JSON contendo o access_token, token_type, refresh_token, expires_in e scope

   { 
     “access_token”: “111”, 
     “token_type”: “bearer”, 
     "refresh_token": "abcd", 
     “expires_in”: 7431095, 
     “scope”: “read” 
    }

Authorization Code

Esse fluxo deve ser utilizado por aplicações que queiram acessar as informações privadas das contas de usuários dos sistemas STI, como por exemplo: turmas de um usuário, frequências de um discente, histórico de utilização de um usuário no restaurante universitário, etc. Assim, aplicações com esse propósito precisam seguir os passos abaixo:

1. O usuário inicia a interação com a aplicação;
2. A aplicação faz uma requisição GET ao authorization server através da URL /authz-server/oauth/authorize, passando os parâmetros client_id, response_type e redirect_uri como QueryParam;

   URL-BASE/authz-server/oauth/authorize?client_id=AppId&response_type=code&redirect_uri=http://enderecoapp.com.br/pagina

3. O usuário é redirecionado para o authorization server. Na página de autenticação exibida, deve informar suas credenciais (username, password) e, em seguida, informar se autoriza que a aplicação utilize seus dados. Para garantir a segurança das informações dos usuários, a página de autenticação exibida é a do servidor de autenticação da Superintendência de Tecnologia da Informação (STI/UFRN). Além disso, vale ressaltar que são os usuários que realizam a autorização do uso dos dados disponibilizados pelos serviços da API;
   
   
   

   Atenção! No ambiente de testes da API, o Nome do usuário é igual ao login dos sistemas da STI e a senha é igual ao login, isto é, no campo senha será inserido o valor do login novamente e não a senha real. No ambiente de produção da API esses campos são, respectivamente, o login e senha dos sistemas da STI.

4. O authorization server retorna o código de autorização para a aplicação;
5. Em posse desse código, a aplicação pode usá-lo para obter um access_token para o usuário. Desse modo, ela realiza uma nova requisição, que neste caso é do tipo POST, ao authorization_server através da URL URL-BASE/authz-server/oauth/token, passando os parâmetros client_id, client_secret, redirect_uri, grant_type e code como QueryParam;
   Ex.:

   POST URL-BASE/authz-server/oauth/token?client_id=AppId&client_secret=AppSecret&redirect_uri=http://enderecoapp.com.br/pagina&grant_type=authorization_code&code=code
                                                       

6. O authorization server retorna à aplicação um JSON contendo o access_token, token_type, refresh_token, expires_in e scope;

   { 
     “access_token”: “111”, 
     “token_type”: “bearer”, 
     "refresh_token": "abcd", 
     “expires_in”: 7431095, 
     “scope”: “read” 
    }

Refresh Token

O fluxo de Refresh Token deve ser utilizado quando o access_token de um usuário expira em aplicações que utilizem os fluxos de autorização Authorization Code e Client Credentials, disponibilizados pela API de serviços da STI. Assim, elas devem seguir os passos abaixo:

1. A aplicação deve fazer uma requisição POST ao servidor de autorização através da URL http://api.info.ufrn.br/authz-server/oauth/token, passando os parâmetros client_id, client_secret, grant_type e refresh_token como QueryParam; Ex.:

   POST URL-BASE/authz-server/oauth/token?client_id=AppId&client_secret=AppSecret&grant_type=refresh_token&refresh_token=abcd

2. O authorization server retorna à aplicação um JSON contendo o access_token, token_type, refresh_token, expires_in e scope;

   { 
     “access_token”: “111”, 
     “token_type”: “bearer”, 
     "refresh_token": "abcd", 
     “expires_in”: 7431095, 
     “scope”: “read” 
    }

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

 GET URL-BASE/discente/VERSAO/discentes?nivel=G 

 GET URL-BASE/discente/VERSAO/discentes/23232 

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.

Android

Bib Inventário

Campus Seguro UFRN

OLAR

Manual do Aluno

VEMCAR

SIGAA

Biblioteca UFRN

RU UFRN

iOS

Campus Seguro UFRN

OLAR

SIGAA

Web

Serviços da UFRN

Hubview

Pedagógico

Labs

Reuse

Cronus

Multiprova

Intellectus

Inova

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