Primeiros passos no uso da API do OpenRedu - Criando aplicativos Canvas

Olá pessoal,

O OpenRedu tem uma funcionalidade muito bacana, é possível embutir conteúdo multimídia dentro de uma Disciplina ou Aula, imagina programar dentro do OpenRedu, assistir uma animação para assimilar melhor o assunto estudado em aula, ou mesmo interagir com o seu professor numa aula totalmente interativa em vídeo. Todas essas coisas são inteiramente possíveis com o OpenRedu, basta liberar a imaginação que o OpenRedu te permitirá se divertir com vendo essas coisas acontecerem, essa é a magia dessa ferramenta, criar oportunidades de aprendizagem que excedem a experiência atual de sala de aula.

O que é Canvas?
O Canvas é uma porção (região de dimensões limitadas) do OpenRedu onde você pode embutir conteúdo dinâmico vindo de outra fonte, o que inclui: vídeos, animações ou qualquer outro tipo de conteúdo interativo.
O Canvas propriamente dito é um <iframe> que tem como fonte um endereço em outro servidor. Este modelo já é bem conhecido e utilizado em outras plataformas de aplicativos, como o Facebook.

O OpenRedu também conta com uma Plataforma de Aplicativos, onde é possível criar aplicações Canvas e embuti-las em uma Disciplina ou Aula através da interface visual, mas veremos como todas essas coisas através da API. Show? hehehehe.

Como já introduzimos o Postman na postagem anterior, vamos usá-lo agora. Antes de prosseguir é importante que você tenha visto a postagem Primeiros passos no uso da API do OpenRedu - Entendendo a hierarquia do OpenRedu para uma compreensão da hierarquia do OpenRedu. Uma vez que você já conhece o cenário da instituição OpenEduca, nossa meta agora é ajudá-la a usar a API.

Criando aplicativo Canvas numa Disciplina (ou também conhecida como Espaço)

Um aplicativo tipo Canvas pode ser criado numa Disciplina ou Aula. Vejamos a primeira opção, de como usar o Canvas numa Disciplina. Uma aplicação Canvas numa Disciplina é indicada para recursos que são úteis em todo o contexto da Disciplina, ou que vão ser compartilhados por Aulas diferentes em diferentes Módulos. Para a Disciplina que utilizaremos logo a seguir, bons candidatos para Canvas são compiladores online, sistemas de submissão de exercícios e sistemas de simulações de competições algorítmicas.
Vamos usar a Disciplina chamada “Algoritmos e Estrutura de Dados”, ela está localizada aqui http://openredu.com/espacos/277. É importante notar que toda entidade no OpenRedu é unicamente identificada através de um ID e, em alguns casos, um path. Através da URL http://openredu.com/espacos/277 podemos identificar que a nossa Disciplina tem ID 277, guarde bem esse valor que o usaremos já já.

O que queremos criar agora é um Canvas numa Disciplina, a documentação da API (http://developers.openredu.com/resources/canvas.html) nos fornece o seguinte endpoint para essa finalidade:
http://openredu.com/api/spaces/:id/canvas
Com os seguintes parâmetros:
canvas[current_url] ~> URL que será exibida no Canvas
canvas[name] ~> Nome mostrado nos links para o Canvas

Como queremos enviar informações para o servidor, faremos uma requisição HTTP do tipo POST, você pode estar achando estranho a palavra canvas se repetindo no nome do parâmetro e outra palavra dentro de colchetes. A explicação para isso é que em requisições POST, geralmente, enviamos nossas informações dentro do corpo da mensagem (payload) não necessitando assim passar parâmetros adicionais na requisição. Podemos enviar as informações sobre o Canvas que queremos criar passando os parâmetros como querystring ou passando um objeto serializado no corpo da mensagem que contém os campos current_url e name, para os objetos serializados, só precisamos informar os nomes que estão entre os colchetes.
Como estamos usando a ferramenta Postman, é mais simples passar parâmetros para a requisição, como já estamos fazendo.

Vamos agora montar nossa requisição POST:
O ID da nossa Disciplina é 277.
A URL que queremos exibir dentro do Canvas será www.codepit.io (um exemplo de sistema de simulação de competição algorítmica).
O nome que queremos seja exibido para o nosso Canvas é Codepit.

Repare que toda entidade é unicamente identificada por um ID ou path (em alguns casos), indicamos que estamos nos referindo à Disciplina 277 fornecendo o seu ID logo após spaces/ (identificador do recurso da API), sendo assim, :id é o ID da nossa Disciplina onde desejamos criar o Canvas. Juntando tudo teremos a seguinte URL:
http://openredu.com/api/spaces/277/canvas
Com os seguintes parâmetros:
canvas[current_url]=http://www.codepit.io
canvas[name]=Codepit

Vamos agora testar se tá tudo certinho, abramos o Postman:

Escolhemos a tipo da requisição HTTP para POST ao clicar no menu dropdown, colocamos a URL que montamos anteriormente, adicionamos os parâmetros depois de apertar o botão “Params”. Está tudo pronto, agora basta usar o Access Token que já temos guardado (se você não tem, é só dar uma olhadinha em Primeiros passos no uso da API do OpenRedu - Usando o Postman), sendo assim, apertemos o botão laranja “Use Token”. No final, teremos:

Ao enviar a requisição HTTP, você vai se deparar com a seguinte mensagem de resposta do servidor:

O que temos aqui é a resposta do OpenRedu com a representação em formato JSON do Canvas que acabamos de pedir para ser criado, ao fazermos requisições POST, o servidor nos retorna o objeto criado a partir das informações que enviamos anteriormente. Para vermos o nosso Canvas em ação, vamos pegar o link self_link, que nos dá a localização do Canvas na interface web do OpenRedu.

Olha ele aqui http://openredu.com/espacos/277/canvas/9, ao navegarmos nesse endereço, podemos ver o nosso Canvas.

E aí, gostou? Espero que tenha gostado. Sinta-se livre para testar outros conteúdos para o seu Canvas, mas atente-se que existem algumas limitações a respeito das dimensões do mesmo. Atualmente é possível inserir aplicações Canvas de até 720px de largura. Em relação à altura só é necessária que ela seja fixa, ou seja, que se mantenha a mesma desde o momento em que ela é carregada.

Criando aplicativo Canvas numa Aula

É só conferir aqui.

Muito obrigado, tudo de bom para vocês e muita diversão com a API.

Oi Horácio,

Segui todo o tutorial e deu certo aqui:

Agora duas perguntas:

  1. Como faço para remover um canvas criado? É necessário excluir o Token junto?

  2. Na versão que estou usando do Openredu (Development), em máquina virtual, onde eu posso alterar a URL, apontando corretamente, assim aparecer os endereços corretos quando do POST pelo Postman, pois aqui apareceu assim com localhost:
    { "id": 1, "name": "voxel.css", "current_url": "http://www.voxelcss.com/demo", "created_at": "2016-08-25T13:24:16-03:00", "updated_at": "2016-08-25T13:24:16-03:00", "container_type": "Space", "links": [ { "rel": "raw", "href": "http://www.voxelcss.com/demo" }, { "rel": "self", "href": "http://127.0.0.1:3000/api/canvas/1" }, { "rel": "self_link", "href": "http://127.0.0.1:3000/espacos/1/canvas/1" }, { "rel": "container", "href": "http://127.0.0.1:3000/api/spaces/1" } ] }

@jonas Opa :D,

Fico muito feliz que tenha dado certo. Respondendo às duas perguntas:
1 - O access token pertence somente ao usuário e é o código que lhe permite consumir a API do OpenRedu, sendo assim, qualquer operação dentro da API não invalida ou destrói de alguma maneira o access token, ele será sempre válido. E também não precisa ser renovado, em outras APIs o acess token expira depois de um tempo e se faz necessário renová-lo, não é o caso do OpenRedu onde os access tokens duram para sempre ajuda bastante.
Para que você possa remover um canvas criado será necessário saber o seu id. Pelo JSON que foi retornado por tua instância do OpenRedu, o canvas que tu criou tem id 1.

Vamos guardar esse id para usarmos logo em seguida. Segundo a documentação, o endpoint da API responsável pela remoção de um canvas é o seguinte:
Método Endpoint
DELETE /api/canvas/:id

Agora, teremos que montar uma requisição HTTP que satisfaça as duas condições acima. Para o teu caso a URI final seria:
http://openredu.ifac.edu.br/api/canvas/1?acess_token=ACCESS_TOKEN
Essa mesma URI é a que é retornada pelo servidor na criação do canvas. No JSON que tu postou tem ela mesminha aqui, só que nesse caso ela está com problemas:

Você pode usar sempre a URI dentro de links->rel=="self" para obter informações do recurso (usando o método GET), ou remover o recurso da instância (usando o método DELETE) através da API.
Agora que já montamos a URI precisamos satisfazer a outra condição de que é disparar a requisição para a API usando o método DELETE.

Usando o Postman ficaria bem similar:

Não estranha se o servidor não retornar nada depois de disparar a requisição para remoção do canvas é assim mesmo, mas depois você pode se certificar de que o canvas foi removido recarregando a página dele e vendo que ele não aparece mais.

2 - Rapaz, isso é bem estranho, o endereço openredu.ifac.edu.br é mapeado para o IP 200.129.147.31, isso quer dizer que o mapeamento tá funcionando corretamente a nível de DNS. Acredito que esteja faltando algum tipo de configuração que remova esse retorno localhost e retorne de fato o endereço onde o OpenRedu tá hospedado. Eu chequei aqui, com o Postman, usando tanto o endereço quanto o IP e ambos retornam localhost como retorno da criação de um canvas. @bouckaert é preciso configurar alguma informação de IP e endereço para a API do OpenRedu?

@horaciojcfilho,
01 - Vou fazer os testes aqui pra remover… logo “feedbeco”

02 - Bem, lembro que para configurar o SMTP foi necessário alterar a linha config.url no arquivo development.rb assim:

Editei o arquivo: OpenRedu/config/environments/development.rb
Alterei a linha: config.url = “0.0.0.0:3000” colocando a URL correta da minha aplicação

Será se tem mais algo a ser alterado para que a requisição do canvas reflita também a URL informada?

Outra coisa, vi que atualmente uma limitação do canvas é de permitir inserir aplicações de até 720px de largura.

Existe alguma forma de o link que chama o aplicativo externo abrir em um pop-up, nova aba, ou em uma janela Modal, invés de um IFrame?

Olá,

01 - Comunicando que consegui a remoção do canvas conforme sua explicação.

02 - Registrando como que o @horaciojcfilho ajudou a resolver:

Editei o arquivo: /config/environments/development.rb

config.url = “minhainstancia.meudominio.com.br”
config.representer.default_url_options = {:host => “minhainstancia.meudominio.com.br”}

Editei ainda o arquivo: /config/application.rb na linha:
config.representer.default_url_options = {:host => “minhainstancia.meudominio.com.br”}

1 Curtida

Muito feliz em saber que deu certo. Dou os créditos do sucesso todo a você :grin:.

1 Curtida

@horaciojcfilho, sabe se isso é possível?

Existe alguma forma de o link que chama o aplicativo externo abrir em um pop-up, nova aba, ou em uma janela Modal, invés de um IFrame?

Oi @jonas, desculpas pela demora em responder. Isso que você deseja não seria oficialmente possível, é que a ideia mesmo de uma aplicação Canvas é de ser exibida dentro de um iframe. Podemos resolver isso de outra maneira? :smiley:

Tudo bem.

Como o IFRAME tem a limitação de largura, pensei em contornar isso abrindo em uma janela Modal ou algo do tipo.

Talvez se o design fosse fluid/liquid não teria esta dificuldade.

Vou tentar encontrar recursos para integrar mais enxutos… obrigado!

É possível anexar um aplicativo canvas no Curso, ou é somente na Discplina e na Aula?