solaredx Documentation

Transcrição

1 solaredx Documentation Release 0.5 Pedro Vasconcelos April 29, 2014

2

3 Contents 1 Índice Instalação e Configuração API-v Login Outras informações i

4 ii

5 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

6 2 Contents

7 CHAPTER 1 Índice 1.1 Instalação e Configuração Instalar e configurar o SolarEDX na sua instalação EDX é simples. Veja abaixo: Instalação 1. Instale a dependência abaixo: django-tastypie ( 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 ou anteriores). 2. Instale o SolarEDX a partir do GitHub. $ pip install git+git://github.com/wwagner33/django-solaredx.git 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

8 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 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; 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

9 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 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/ 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 :53: ", " ": "ptronico@gmail.com", "is_active": true, "name": null, "resource_uri": "/solaredx/api/v1/user/ptronico/", "username": "ptronico", "date_joined": "Wed, 2 Oct :56: ", " ": "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 API-v1 5

10 Filtrando usuários Você pode adicionar alguns filtros a sua consulta. É possível filtrar os campos date_joined, username e . Para isso, você deverá usar a mesma sistemática de field lookups adotada pela ORM do Django. Por exemplo, para listar usuários cujo seja do Gmail, faça uma requisição como a que se segue: $ curl 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 gte= :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: :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 GET /solaredx/api/v1/user/ptronico/ HTTP/1.1 Essa requisição retorna o seguinte: HTTP/ OK "course_resource_uri": "/solaredx/api/v1/user/ptronico/course/", "date_joined": "Wed, 2 Oct :53: ", " ": "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 GET /solaredx/api/v1/user/fulano/ HTTP/1.1 E a respectiva resposta (apenas cabeçalho, não retorna dados): HTTP/ 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, e name codificandos em JSON. Veja o exemplo abaixo: 6 Chapter 1. Índice

11 $ curl --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/ CREATED " ": "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 --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/ BAD REQUEST " ": [ " 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

12 $ curl -X PATCH --header Content-Type: applicat PATCH /solaredx/api/v1/user/ptronico/ HTTP/1.1 Observe a resposta: HTTP/ 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 GET /solaredx/api/v1/user/ptronico/course/ HTTP/1.1 Como resposta temos: HTTP/ OK [ ] "/solaredx/api/v1/course/ f f e32/", "/solaredx/api/v1/course/ f f f46616c6c/", "/solaredx/api/v1/course/ f f e32/", "/solaredx/api/v1/course/ f f f3031/" 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 -X POST --header Content-Type: ap POST /solaredx/api/v1/user/ptronico/course/ HTTP/1.1 Vejamos a reposta da requisição acima: HTTP/ CREATED 8 Chapter 1. Índice

13 "course_resource_uri": "/solaredx/api/v1/course/ f f e32/" 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 -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/ NO CONTENT Content-Type: text/html; charset=utf 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 O JSON retornado segue abaixo: HTTP/ OK "meta": "limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 2, "objects": [ "course_absolute_url": " "course_absolute_url_lms": " "course_absolute_url_studio": " "course_id": "UFC/CS101/2013_Fall", "display_name": "Introduction to Computer Science", "end": "Fri, 1 Nov :00: ", "enrollment_end": "Fri, 25 Oct :30: ", "enrollment_start": "Mon, 21 Oct :00: ", 1.2. API-v1 9

14 ], "resource_uri": "/solaredx/api/v1/course/ f f f46616c6c/", "start": "Mon, 28 Oct :00: " "course_absolute_url": " "course_absolute_url_lms": " "course_absolute_url_studio": " "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/ f f e32/", "start": "Wed, 31 Dec :00: " Criação e exclusão de cursos Criação Requisição: $ curl -X POST --header Resposta: HTTP/ CREATED "course_creator_username": "ptronico", "course_id": "UFC/C005/2014.1", "display_name": "Novo Curso", "resource_uri": "/solaredx/api/v1/course/ f f e31/" Exclusão Requisição: $ curl -X DELETE --heade Resposta (não são retornado dados): HTTP/ 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

15 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: $ Resposta: HTTP/ 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: $ -X POST --he O retorno... HTTP/ 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: $ -X DELETE -- Resposta (não retorna dados): HTTP/ NO CONTENT Content-Type: text/html; charset=utf API-v1 11

16 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: 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