Fork me on GitHub

Introdução

O Redu é uma plataforma de ensino a distância construída sobre uma rede social. Através da API HTTP REST do Redu é possível construir aplicações que acessam os dados dos usuários da plataforma.

Dizer que uma API pode ser utilizada via HTTP implica dizer que não há restrições quanto a linguagem ou tecnologias utilizadas na integração de aplicativos. Por se tratar do protocolo de aplicação da internet, qualquer linguagem moderna é capaz de enviar requisições HTTP.

Primeiros passos

1. Criação de credenciais

Antes de consumir a API é necessário cadastrar o aplicativo. Para cadastrar vá na opção Aplicativos na sua página incial do Redu. Você precisa informar Nome e URL do seu aplicativo. O nome será mostrado para o usuário quando o aplicativo estiver pedindo autorização para o acesso a dados. A URL também é obrigatória e pode ser ou a página inicial do seu aplicativo ou uma página explicativa do mesmo.

Após informar nome e URL do aplicativo, serão mostrada as credenciais do mesmo. Existem dois tipos de credenciais: a chave do consumer e o segredo do consumer. A chave do consumer é um identificador único do seu aplicativo que é utilizada para pedir autorização para o usuário ceder seus dados para o aplicativo. Já o segredo do consumer é um identificador privado que o Redu utiliza identificar o aplicativo que realiza a requisição da API.

2. Autenticação

O Redu não cede dados do usuários sem a expressa autenticação do mesmo. Para que os aplicativos acessem as informações do usuário é necessário que ele autorize explicitamente este acesso. Para isso, o aplicativo precisa implementar o processo de autenticação do usuário. No Redu utilizamos o protocolo OAuth 2.0 para este fim. Tal protocolo é muito difundido e utilizado pelas APIs Twitter, Facebook e Google.

No fim do processo de autenticação do OAuth 2.0 é gerado mais uma credencial chamada de aceess token. Esta credencial identifica unicamente sua aplicação e o usuário que autorizou acesso. Portanto, é necessário enviar o access token em todas as requisições feitas em nome do usuário que autorizou. O access token pode ser enviado via querystring (?access_token=TOKEN) ou pelo cabeçalho Authorization (Authorization: OAuth TOKEN) da requisição HTTP.

Este guia não entra em detalhes sobre a implementação da autenticação via OAuth 2.0. Porém temos exemplos em várias linguagens sobre como realizar esta tarefa. Uma lista com clientes OAuth 2 sugeridos é mostrada abaixo:

Linguagem/Framework Projeto Suporte Oficial?
Ruby On Rails omniauth-redu Sim
Python ReduPy Sim
Java jRedu Sim
Python rauth Não
Django django-social-auth Não
Play! play-pack4j Não
.NET .NET Open Auth Não

3. Consumindo a API REST

Após cadastrar o aplicativo e pedir autorização para o usuário, será possível utilizar a API REST. Por exemplo, ao realizar uma requisição HTTP com o método GET para a URL /api/environments/foo o recurso retornado seria como o descrito abaixo:

{
  name: "Foo",
  created_at: "2010-12-17T16:37:40-02:00",
  initials: "bar",
  path: "foo",
  links: [
    { href: "http://redu.com.br/api/environments/foo", rel: "self" },
    { href: "http://redu.com.br/api/environments/foo/courses", rel: "courses" }
    { href: "http://redu.com.br/api/environments/foo/users", rel: "users" }
  ]
}

Hypertext enabled

Seguindo a sugestão do Roy Fielding, pai do REST, todos os recursos retornados pela API do Redu possuem metainformações (hyperlinks) para outros recursos importantes no estado atual da aplicação. Isso faz com que a API possua um único ponto de entrada, por exemplo o AVA.

Note que a representação retornada possui uma propriedade links que denota as URLs que a aplicação cliente precisa conhecer no contexto atual (visualização do ambiente virtual de aprendizagem). Isso quer dizer que, por exemplo, quisessemos visualizar os cursos do AVA em questão, poderíamos faze-lo sem conhecer a priori a URL apropriada.

Mais informações