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.

Autenticação

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”
    }
client credentials ufrn

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;

    tela login com as credenciais (login e senha iguais)

    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”
    }
authorization code ufrn

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”
    }
refresh token ufrn

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: