D2lvalenceElixir

Desire2Learn Client Library for Elixir

Elixir implementation of d2lvalence to connecto to the Desire2Learn's Valence API.

Based on Desire2Learn Client Library for Python

Works with the Brightspace Api Rest

Auth: The D2lvalenceElixir.Auth module provides assistance for the authentication needed to invoke Valence APIs. You use the module's functiones to create a %D2lvalenceElixir.Auth.D2LUserContext{} struct that you can then employ as an authentication helper.

Service: The D2lvalenceElixir.Utils.Service module provides many functions to call the Brightspace API Rest according to their documentation.

Installation

The package can be installed by adding d2lvalence_elixir to your list of dependencies in mix.exs:

def deps do
  [
    {:d2lvalence_elixir, "~> 0.1.0"}
  ]
end

Documentation

HexDocs

Use

Authentication

defmodule D2lvalenceElixir.Examples.SimpleAuthentication do
  alias D2lvalenceElixir.Auth.D2LAppContext
  alias D2lvalenceElixir.Auth.D2LUserContext
  alias D2lvalenceElixir.Auth.D2LUserContextSimple
  alias D2lvalenceElixir.Auth

  def get_url_to_authenticate(app_id, app_key) do
    # You recieve the app_id and the app_key and then use the host
    # of your Brightspace instance, the callback and True for SSL (https).
    # You send the result URL to the user so he can authenticate and then
    # you recieve the user_key and user_id in the callback url.
    Auth.fashion_app_context(app_id: app_id, app_key: app_key)
    |> D2LAppContext.create_url_for_authentication(
      "bloqueneon.uniandes.edu.co",
      "http://localhost:8080/token",
      true
    )
  end

  def auth_token_handler(result_url, app_id, app_key) do
    # You take the full result url (including https://yourfancyapp:8080/callback) requested after login and then generates the
    # user_context than helps your application with all the authenticated requests to de Brightspace API
    {:ok, full_user_context = %D2LUserContext{}} =
      Auth.fashion_app_context(app_id: app_id, app_key: app_key)
      |> D2LAppContext.create_user_context(
        result_uri: result_url,
        host: "bloqueneon.uniandes.edu.co",
        encrypt_requests: true
      )

    # {full_user_context, simple_user_context}. I recommend to store the simple_user_context on the session
    # for security purposes (You must NOT share the app_id and app_key with the user)
    {full_user_context, full_user_context |> D2LUserContext.get_simple_user_context()}
  end

  def get_full_user_context(%D2LUserContextSimple{} = simple_user_context, app_id, app_key) do
    # If you only stores the D2LUserContextSimple, you have to generate the full_user_context to
    # make authenticated requests to the Brightspace API
    {:ok, %D2LUserContext{} = full_user_context} =
      Auth.fashion_app_context(app_id: app_id, app_key: app_key)
      |> D2LUserContext.get_full_user_context(simple_user_context)

    full_user_context
  end
end

Simple calls

defmodule D2lvalenceElixir.Examples.SimpleApiCalls do
  alias D2lvalenceElixir.Auth.D2LUserContext
  alias D2lvalenceElixir.Utils.Service
  alias D2lvalenceElixir.Data.WhoAmIUser

  def serializers do
    # To encode and decode the requests, you could need some serializers.
    # This function creates the map with the serializers you need.
    # You need an application/json at least.
    %{}
    |> Map.put("application/json", Jason)
  end

  def whoami_api_call(%D2LUserContext{} = user_context) do
    # With the user_context (full_user_context, not simple) you call the whoami
    # You have to send the serializers, at least an application/json to decode the result
    # I use this version because it works on my university
    # The WhoAmI call shows who is the authenticated with the user_context
    {:ok, user = %WhoAmIUser{}} =
      user_context
      |> Service.get_whoami(serializers: serializers(), ver: "1.23")

    user
  end

  def get_all_versions_api_call(%D2LUserContext{} = user_context) do
    # With the user context, shows the information of all the products of the Brightspace instance
    {:ok, products_information} =
      user_context
      |> Service.get_all_versions(serializers: serializers(), ver: "1.23")

    products_information
  end
end