Fork me on GitHub

Introduction

Redu is a distance learning platform built on a social network. By using Redu HTTP REST API, it is possible to build applications which access user data from the platform.

Declaring that an API can be used via HTTP implies in saying that there is no restriction regarding languages or tecnologies used in the integration of applications. Since it is an internet application protocol, any modern language can send HTTP requests.

First steps

1. Creation of credentials

Before consuming the API, you need to register the application. Go to Aplicativos (Applications) on your Redu home page. You need to provide Name and URL for your application. The name will be shown to the user when the application requests access authorization to data. The URL is also required, and it may be either the application home page or a page that explains about it.

After providing name and URL for the application, its credentials will be shown. There are two different types of credentials: consumer key, and consumer secret. The consumer key is a unique identifier of your application, which is used to request authorization to the user to get their data for the application. On the other hand, consumer secret is a private identifier which is used by Redu to identify application that makes the API request.

2. Authentication

Redu does not give data of users without the authentication of them. To allow applications to access user information, the user needs to authorize such access explicitly. For that, the application must implement the authentication process for the user. In Redu, we use the 0Auth 2.0 protocol for this purpose. This protocol is widespread, and it is used by Twitter, Facebook, and Google APIs.

At the end of the OAuth 2.0 authentication process, one more credential is generated, which is called access token. This credential identifies uniquely your application and the user who has authorized access. Therefore, it is necessary to send the access token in every single request done on behalf of the user who has authorized. The access token can be sent either via querystring (?access_token=TOKEN) or through the header Authorization (Authorization: OAuth TOKEN) of HTTP request.

This guide does not go into details about the implementation of authentication via OAuth 2.0. However, we have examples in several languages about how to perform this task. A list of suggested OAuth 2.0 clients is shown below:

Language/Framework Project Official Support?
Ruby On Rails omniauth-redu Yes
Python ReduPy Yes
Java jRedu Yes
Python rauth No
Django django-social-auth No
Play! play-pack4j No
.NET .NET Open Auth No

3. Consuming REST API

After registering the application and requesting authorization for the user, you will be able to use REST API. For instance, when making a HTTP request with GET method to the URL /api/environments/foo, the returned resource would be as follows:

{
  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

Following the suggestion from Roy Fielding, father of REST, every resource returned by Redu API has metadata (hyperlinks) to other important resources in the current state of the application. It causes the API to have a single point of entry, such as the Virtual Learning Environment (VLE).

Note that the returned representation has a property named “links” that denotes URLs which the client application needs to know in this context (visualization of virtual learning environment). It means that, for example, if we wanted to visualize the courses in that environment, we could do it without knowing a priori the appropriate URL.

More information