API REST Cobalto

Para interagir com a API REST cobalto é necessário primeiramente obter uma chave de acesso para sua aplicação, que deverá ser usada em todas as requisições feitas ao serviço que for solicitado. É através desta chave a autenticação do serviço assim com as limitações e os níveis de acesso nos serviços da API. Todos os serviços utilizam a tecnologia REST no tratamento de requisições. Desta forma é possível construir facilmente uma URL para ser executada em seu navegador, linha de comando ou código.

Formato de requisição

A tecnologia REST é a única utilizada em todos os serviços da API do cobalto no tratamento das requisições.

Visão Geral

Transferência de Estado Representacional (Representational State Transfer) ou somente REST é uma técnica de engenharia de software para sistemas distribuídos, que descreve uma interface web simples que utiliza XML, HTTP, JSON ou texto puro, sem abstrações adicionais dos protocolos baseados em padrões de troca de mensagem como o SOAP.

Exemplo de requisição usando REST

http://api-cobalto.ufpel.edu.br/academico/curso/lista_cursos?api_key=CHAVE_ACESSO&format=json

Na URL acima usamos o serviço academico/curso/lista_cursos da API cobalto, que retorna a lista de cursos registrados no sistema cobalto. O parâmetro api_key refere-se a chave de acesso que você obteve para fazer requisições à API e o parâmetro format refere-se ao formato de retorno que você deseja utilizar. Através desta URL de requisição, a API do cobalto lhe retornará um objeto JSON contendo a lista de cursos.

Formatos de retorno

Pode ser usado os formatos de retorno listados abaixo:

• xml "application/xml"
• json "application/json"
• jsonp "application/javascript"
• serialized "application/vnd.php.serialized"
• php "text/plain"
• htm "text/html"
• csv "application/csv"

Exemplo de retorno no formato JSON

 [
  {"id":"1","cod_curso":"1234","nome":"Curso 1","turno":"NOTURNO","nivel":"GRADUAÇÃO"},
  {"id":"2","cod_curso":"4321","nome":"Curso 2","turno":"DIURNO","nivel":"GRADUAÇÃO"}
 ]

Utilizando API REST cobalto

Abaixo exemplos de utilização da API, com PHP e JavaScript.

Usando PHP

Para utilizar a API com php deve ter instalado no servidor a biblioteca [http://php.net/manual/en/book.curl.php cURL]

 $url         = 'http://api-cobalto.ufpel.edu.br/academico/curso/lista_cursos';
 $api_key     = 'AQUI_CHAVE_DE_ACESSO';
 $format      = 'json';
 $parameters  = ' ';
 $curl = curl_init();
 curl_setopt($curl, CURLOPT_URL, $url.'?api_key='.$api_key.'&format='.$format.'&'.$parameters);
 curl_setopt($curl, CURLOPT_HEADER, 0);
 curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
 $result = curl_exec($curl);
 curl_close($curl);
 $cursos = json_decode($result);
 if (isset($cursos->status)){
     echo $cursos->error;
 }else{
     foreach($cursos as $curso){
         echo $curso->id.' # '.$curso->cod_curso.' # '.$curso->nome.' # '.$curso->turno.' # '.$curso->nivel;
     }
 }

Usando Python

O código abaixo exibe um exemplo de utilização com a linguagem Python

 import urllib2
 import simplejson as json
 url        = 'http://api-cobalto.ufpel.edu.br/academico/curso/lista_cursos'
 api_key    = 'AQUI_CHAVE_DE_ACESSO'
 format     = 'json'
 parameters = ' '
 request  = urllib2.Request(url+'?api_key='+api_key+'&format='+format+'&'+parameters, None)
 response = urllib2.urlopen(request)
 cursos   = json.load(response)
 try:
     print cursos['error']
 except TypeError:
     for curso in cursos:
         print curso['id'] + " # " + curso['cod_curso'] + " # " + curso['nome']