solaredx Documentation Release 0.5 Pedro Vasconcelos April 29, 2014
Contents 1 Índice 3 1.1 Instalação e Configuração........................................ 3 1.2 API-v1.................................................. 4 1.3 Login................................................... 12 1.4 Outras informações............................................ 12 i
ii
SolarEDX é um pacote Python, plugavel ao EDX, que permite sua integração com o Solar. Esse pacote implementa, dentre outros recursos, uma API que permite o Solar controlar o EDX. Ações como criar cursos, usuários, gerenciar matrículas, alocar professores e tutores pondem ser realizadas pela API. Contents 1
2 Contents
CHAPTER 1 Índice 1.1 Instalação e Configuração Instalar e configurar o SolarEDX na sua instalação EDX é simples. Veja abaixo: 1.1.1 Instalação 1. Instale a dependência abaixo: django-tastypie 0.9.16 (https://github.com/toastdriven/django-tastypie/tree/v0.9.16) Note: Observe que a versão do Tastypie (django-tastypie) não é a mais recente. Isso ocorre porquê, na época do desenvolvimento do SolarEDX, o EDX utilizava o Django 1.4 (a qual é suportada apenas pelo Tastypie 0.9.16 ou anteriores). 2. Instale o SolarEDX a partir do GitHub. $ pip install git+git://github.com/wwagner33/django-solaredx.git 1.1.2 Configuração Siga os passos abaixo para configuração do SolarEDX na instalação do EDX: 1. Inclua as variáveis abaixo no arquivo de configuração do CMS: AUTHENTICATION_BACKENDS = ( solaredx.backends.solaredxbackend, ) INSTALLED_APPS += ( tastypie, solaredx, ) TASTYPIE_DEFAULT_FORMATS = [ json ] TASTYPIE_DATETIME_FORMATTING = rfc-2822 SOLAREDX_SECRET_KEY = your secret key 2. Inclua as URLs do SolarEDX no arquivo de configuração de URLs do CMS: url(r ^solaredx/, include( solaredx.urls )) 3
1.2 API-v1 Essa documentação cobre a versão v1 da API. Todas as chamadas dessa versão contém, /api/v1/ na URI. Note: Uma regra geral é que todas as requisições de consulta/leitura deverão ser realizadas com HTTP GET, e as requisições de modificação/escrita com HTTP POST, PATCH ou DELETE para criação, modificação ou exclusão, respecitvamente. Todas as requisições retornam o status_code mais adequado o possível. Para mais informações consulte o artigo Status Code Definitions. Utilize o Curl ou a extensão Postman do Chrome para brincar com a API enquanto você lê essa documen- Note: tação. Note: Embora faça parte do pacote SolarEDX, o sistema de login via Solar não está implementado nessa API. O motivo principal é que a arquitetura do Sistema de Login Simplificado quebra os princípios utilizados na API. 1.2.1 Introdução A API provida pelo SolarEDX permite as seguintes chamadas: Chamadas relacionadas à usuários: Criar usuários; Listar usuários; Consultar um usuário; Atualizar um usuário; Listar cursos em que o usuário está matriculado; Matricular e desmatricular usuários; Chamadas relacionadas à cursos: Criar cursos; Listar cursos; Consultar um curso; Deletar um curso; Listar professores e tutures de um curso; Associar professores e tutores à um curso; Desassociar professores e tutores à um curso; 1.2.2 Sistema de Segurança / Autenticação Uma vez que a API provida pelo SolarEDX permite ações globais de controle e, em decorrência disso, o acesso será restrito à apenas clientes autorizados e com IP fixo (por exemplo, o servidor do Solar). Nesse caso, a restrição de acesso deverá ser configurada no servidor do EDX, de modo a bloquear qualquer requisição à API que venha de um IP não autorizado. Note: O módulo ngx_http_access_module permite a instalação desse sistema de segurança com o Nginx. 4 Chapter 1. Índice
1.2.3 Gestão de Usuários Essa sessão apresenta como gerenciar usuários. Listagem e consulta de usuários Para efetuar uma listagem geral de usuários do EDX, faça uma requisição GET, como segue no exemplo abaixo. Observe que o primeiro bloco é um comando que utiliza o curl para fazer a requisição, e o segundo bloco é o cabeçalho da requisição realizada: $ curl http://localhost:8001/solaredx/api/v1/user/ GET /solaredx/api/v1/user/ptronico/course/ HTTP/1.1 Veja os dados retornados da requisição acima. O primeiro bloco consiste no cabeçalho da resposta. O segundo, nos dados recebidos, em formato JSON: HTTP/1.0 200 OK Server: WSGIServer/0.1 Python/2.7.1 "meta": "limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 2, "objects": [ "date_joined": "Wed, 2 Oct 2013 13:53:50-0300", "email": "ptronico@gmail.com", "is_active": true, "name": null, "resource_uri": "/solaredx/api/v1/user/ptronico/", "username": "ptronico", "date_joined": "Wed, 2 Oct 2013 13:56:31-0300", "email": "pedro@pedrorafa.com", "is_active": true, "name": null, "resource_uri": "/solaredx/api/v1/user/pedrorafa/", "username": "pedrorafa" ] Note: Os cabeçalhos mostrados na nessa documentação, tanto da da requisição e da resposta, tem o objetivo de mostrar as informações essenciais para a realização da requisição e correto recebimento da resposta, e portanto podem ter alguns de seus elementos suprimidos. 1.2. API-v1 5
Filtrando usuários Você pode adicionar alguns filtros a sua consulta. É possível filtrar os campos date_joined, username e email. Para isso, você deverá usar a mesma sistemática de field lookups adotada pela ORM do Django. Por exemplo, para listar usuários cujo email seja do Gmail, faça uma requisição como a que se segue: $ curl http://localhost:8001/solaredx/api/v1/user/?email icontains=@gmail.com Para filtrar usuários cujo cadastro ocorreu a partir de uma determinada data, faça uma requisição semelhante a que segue abaixo: $ curl http://localhost:8001/solaredx/api/v1/user/?date_joined gte=2013-10-02 13:55:00-03:00 Note que para o campo date_joined só será aceito uma data no formato YYYY-MM-DD HH:MM[:ss[.uuuuuu]][TZ]. Ex: 2013-10-02 13:55:00-03:00, onde -03:00 é o fuso-horário. Consultando um usuário Para consultar um usuário, basta acessar a URI contida no campo resource_uri desse usuário. Por exemplo: $ curl http://localhost:8001/solaredx/api/v1/user/ptronico/ GET /solaredx/api/v1/user/ptronico/ HTTP/1.1 Essa requisição retorna o seguinte: HTTP/1.0 200 OK "course_resource_uri": "/solaredx/api/v1/user/ptronico/course/", "date_joined": "Wed, 2 Oct 2013 13:53:50-0300", "email": "ptronico@gmail.com", "name": "Pedro Vasconcelos", "username": "ptronico" Se você consultar um usuário que não existe será retornado uma resposta 404 NOT FOUND. Veja a requição abaixo: $ curl http://localhost:8001/solaredx/api/v1/user/fulano/ GET /solaredx/api/v1/user/fulano/ HTTP/1.1 E a respectiva resposta (apenas cabeçalho, não retorna dados): HTTP/1.0 404 NOT FOUND Content-Type: text/html; charset=utf-8 Criação, modificação e exclusão de usuários Criando um usuário A operação de criação de usuários ocorre mediante uma requisição HTTP POST para a URI de listagem de usuários, isto é, /api/v1/user/, enviando os campos username, email e name codificandos em JSON. Veja o exemplo abaixo: 6 Chapter 1. Índice
$ curl http://localhost:8001/solaredx/api/v1/user/ --header --data POST /solaredx/api/v1/user/ HTTP/1.1 Caso a operação seja efetuada com sucesso, será retornado uma resposta 201 CREATED. Veja a resposta da requisição acima: HTTP/1.0 201 CREATED "email": "ptronico@gmail.com", "name": "Pedro Vasconcelos", "username": "ptronico", "resource_uri": "/solaredx/api/v1/user/ptronico/" Durante todas as requisições de modificações ou deleções de dados, bem como no caso da criação de usuário, há a validação dos dados da requisição. Para efeito de demonstração, iremos tentar criar um usuário já existente. Para isso iremos repetir a requisição anteior. Observe a requisição abaixo: $ curl http://localhost:8001/solaredx/api/v1/user/ --header --data POST /solaredx/api/v1/user/ HTTP/1.1 Observe que a resposta da requisição retornou a informação 400 BAD REQUEST. O JSON retornado também segue abaixo: HTTP/1.0 400 BAD REQUEST "email": [ "Email already exists!" ], "username": [ "Username already exists!" ] Observe que no JSON retornado há uma mensagem informando o motivo pelo qual a requisição foi retornada como Bad Request. Note: Sempre que uma requisição não for realizada com sucesso, por exemplo, por envio incorreto de dados, será retornado 400 BAD REQUEST. Isso vale para qualquer requisição incorreta. Modificando um usuário Para modificar um usuário, faça uma requisição semelhante à requisição de criar usuário, com o valor do campo action igual a update. Veja o exemplo abaixo: 1.2. API-v1 7
$ curl http://localhost:8001/solaredx/api/v1/user/ptronico/ -X PATCH --header Content-Type: applicat PATCH /solaredx/api/v1/user/ptronico/ HTTP/1.1 Observe a resposta: HTTP/1.0 202 ACCEPTED "name": "Pedro Rafael A. C. Vasconcelos" Alocação e desalocação de usuários em cursos (matrícula) Para consultar em quais cursos o usuário está matriculado, course_resource_uri do usuário. Veja o exemplo abaixo: iremos acessar a URI contida no campo $ curl http://localhost:8001/solaredx/api/v1/user/ptronico/course/ GET /solaredx/api/v1/user/ptronico/course/ HTTP/1.1 Como resposta temos: HTTP/1.0 200 OK [ ] "/solaredx/api/v1/course/5546432f433030322f323031342e32/", "/solaredx/api/v1/course/5546432f43533130312f323031335f46616c6c/", "/solaredx/api/v1/course/5546432f43533130322f323031342e32/", "/solaredx/api/v1/course/5546432f43543130312f323031345f3031/" Alocando um usuário em um curso Para alocar (matricular) um usuário em um curso, deve-se fazer uma requisição HTTP POST para a URI /api/v1/user/<username>/course/ com os campos course_id e action (com o valor add). Veja o exemplo abaixo: $ curl http://localhost:8001/solaredx/api/v1/user/ptronico/course/ -X POST --header Content-Type: ap POST /solaredx/api/v1/user/ptronico/course/ HTTP/1.1 Vejamos a reposta da requisição acima: HTTP/1.0 201 CREATED 8 Chapter 1. Índice
"course_resource_uri": "/solaredx/api/v1/course/5546432f43533130322f323031342e32/" Desalocando um usuário em um curso Para desalocar (desmatricular) um usuário em um curso, deve-se fazer uma requisição HTTP POST para a URI /api/v1/user/<username>/course/ com os campos course_id e action (com o valor remove). Essa chamada é similar a de matrícula. Veja o exemplo abaixo: $ curl http://localhost:8001/solaredx/api/v1/user/ptronico/course/ -X DELETE --header Content-Type: DELETE /solaredx/api/v1/user/ptronico/course/ HTTP/1.1 Vejamos a reposta da requisição acima (essa resposta não retorna dados ): HTTP/1.0 204 NO CONTENT Content-Type: text/html; charset=utf-8 1.2.4 Gestão de Cursos Essa sessão apresenta como gerenciar cursos. Consulta e listagem de cursos Para listar cursos acesse a URI /solaredx/api/v1/course/. Veja o exemplo abaixo: $ curl http://localhost:8001/solaredx/api/v1/course/ O JSON retornado segue abaixo: HTTP/1.0 200 OK "meta": "limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 2, "objects": [ "course_absolute_url": "http://solaredx.virtual.ufc.br/courses/ufc/cs101/2013_fall/about" "course_absolute_url_lms": "http://solaredx.virtual.ufc.br/courses/ufc/cs101/2013_fall/in "course_absolute_url_studio": "http://solaredxstd.virtual.ufc.br/course/ufc.cs101.2013_fa "course_id": "UFC/CS101/2013_Fall", "display_name": "Introduction to Computer Science", "end": "Fri, 1 Nov 2013 12:00:00-0300", "enrollment_end": "Fri, 25 Oct 2013 23:30:00-0300", "enrollment_start": "Mon, 21 Oct 2013 00:00:00-0300", 1.2. API-v1 9
], "resource_uri": "/solaredx/api/v1/course/5546432f43533130312f323031335f46616c6c/", "start": "Mon, 28 Oct 2013 08:00:00-0300" "course_absolute_url": "http://solaredx.virtual.ufc.br/courses/ufc/cs102/2014.2/about", "course_absolute_url_lms": "http://solaredx.virtual.ufc.br/courses/ufc/cs102/2014.2/info" "course_absolute_url_studio": "http://solaredxstd.virtual.ufc.br/course/ufc.cs102.2014.2/ "course_id": "UFC/CS102/2014.2", "display_name": "Teste de cria\u00e7\u00e3o de curso", "end": null, "enrollment_end": null, "enrollment_start": null, "resource_uri": "/solaredx/api/v1/course/5546432f43533130322f323031342e32/", "start": "Wed, 31 Dec 1969 21:00:00-0300" Criação e exclusão de cursos Criação Requisição: $ curl http://localhost:8001/solaredx/api/v1/course/ -X POST --header Resposta: HTTP/1.0 201 CREATED "course_creator_username": "ptronico", "course_id": "UFC/C005/2014.1", "display_name": "Novo Curso", "resource_uri": "/solaredx/api/v1/course/5546432f433030352f323031342e31/" Exclusão Requisição: $ curl http://localhost:8001/solaredx/api/v1/course/5546432f433030312f323031342e31/ -X DELETE --heade Resposta (não são retornado dados): HTTP/1.0 204 NO CONTENT Content-Type: text/html; charset=utf-8 Alocação e desalocação de professores e tutores em cursos As operações de consulta de professores e tutores alocados em um curso, bem como as requisições de alocação e desalocação de professores e tutores são idênticas, diferenciando apenas o endpoint, sendo o 10 Chapter 1. Índice
instructor_resource_uri para operações com Professores e o staff_resource_uri para operações com Tutores. Note: Entende-se por instructor o Professor e staff o Tutor. Consultando professores e tutores alocados em um curso Requisição: $ http://localhost:8001/solaredx/api/v1/course/5546432f43543130312f323031345f3031/staff/ Resposta: HTTP/1.0 200 OK [ ] "/solaredx/api/v1/user/ptronico/" Alocando professores e tutores em um curso Para alocar um usuário como professor ou tutor em um curso, deve-se fazer uma requisição HTTP POST para uma das URIs dos campos instructor_resource_uri ou staff_resource_uri. Deve-se enviar os campos course_id e action (com o valor add para adicionar ou remove para remover). No exemplo abaixo iremos alocar um Professor em um curso: $ http://localhost:8001/solaredx/api/v1/course/5546432f43543130312f323031345f3031/staff/ -X POST --he O retorno... HTTP/1.0 201 CREATED "user_resource_uri": "/solaredx/api/v1/ptronico/" Note: Se você tentar alocar um professor ou tutor que já esteja alocado, você receberá uma resposta 400 BAD REQUEST. Desalocando professores e tutores em um curso Requisição: $ http://localhost:8001/solaredx/api/v1/course/5546432f43543130312f323031345f3031/staff/ -X DELETE -- Resposta (não retorna dados): HTTP/1.0 204 NO CONTENT Content-Type: text/html; charset=utf-8 1.2. API-v1 11
1.3 Login Idealmente o sistema de autenticação deverá ser implementado utilizando o protocolo OAuth2. Quando isso ocorrer o sistema de login fará parte da API do pacote SolarEDX. Enquanto isso, será utilizado um sistema de autenticação simplificado, descrito abaixo: 1.3.1 Sistema de login simplificado O sistema de login simplificado consiste em uma requisição POST com destino à URL /login/ do SolarEDX. O próprio usuário deverá efetuar essa requisição, pois o SolarEDX irá autenticar a sua sessão de acesso. Note: Um formulário html com campos ocultos é capaz de tornar essa requisição tão simples quanto o clique em um link. O token de autenticação deverá ser gerado utilizando HMAC e função de hash SHA1. O valor a ser criptografado deve ser o username do usuário. A key (chave) deverá ser fornecida pelo Solar, no ato da instalação do SolarEDX (veja a variável SOLAREDX_SECRET_KEY em Configuração). Por fim, o resultado da criptografia deverá ser codificado em hexadecimal. Veja abaixo um exemplo de login, realizado com a extensão Postman Google Chrome: 1.4 Outras informações Consulte Changelog para acompanhar o histórico de atualizações do pacote. 12 Chapter 1. Índice