Using a custom resource library

Lessonspace provides a resource library that can be used by teachers to insert content into a space. Usually it comes pre-filled with some useful content, and it can be updated by using the Library tab from your dashboard. It's also possible to provide a custom API endpoint from which the resource library will fetch data from.

Authentication & CORS

There are two possible ways to authenticate resource library requests (and it's also possible to not authenticate them at all!). Whichever approach you use, CORS will also be required.

CORS setup

You'll need to ensure your endpoints all allow CORS access for go.room.sh, and you might need to expose some specific headers if you choose to use the header method below.

Using headers, the JWT and the Room secret

Each request will contain two headers:

• X-Holodeck-JWT The current user's JWT which is signed with the space (secret returned by the Launch API).
• X-Holodeck-Room The current space ID. This is Lessonspace's internal UUID that you get back from the Launch API.

You can use these to validate the provided JWT against the returned secret to ensure the user has the expected permissions.

Using secret URLs

It's also possible to embed any query parameters in the library URL. For example, you could make the root URL be https://api.example.com/resources/tabs/?token=abc. This is a simpler option to using custom headers and JWTs as described above.

Types of content

The resource library currently supports three types of resources. Images, exported Lessonspace ZIPs and PDFs.

The three APIs required

The resource library works in three steps. On page load, a GET request is done to fetch a list of tabs and the URL associated with each one.

When the resource library is opened, two GET requests are made to the folder and tab endpoint respectively. The tab endpoint is just the URL specified in the tabs response, while the folders endpoint will have /folders/ appended to it.

Step 1: The Tabs Endpoint

This is a listing of all the tabs to display for the library. These are presented across the left hand side of the screen, such as "Personal", "Organisation" in the screenshot above. The JSON payload needs to be an array of objects, each having a title, an icon (which will be an SVG) and a URL.

Your endpoint needs to return data that looks like:

[
  {
    "id": 1,
    "title": "Personal",
    "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"1.1\" width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"currentColor\">...</svg>",
    "url": "https://example.com/path/to/tab/endpoint"
  }
]

Step 2: The Folder Endpoint

This endpoint is optional, but required if you want to enable folder support. Currently folders can only be one level deep and are displayed at the root of each tab.

Given the tab endpoint from the above example, the folder endpoint will be automatically calculated as https://example.com/path/to/tab/endpoint/folders/

When a folder is selected, it's ID will be included as a query parameter in the request to the tab endpoint as described in step 3 below.

Your endpoint needs to return data that looks like:

{
   "count": 1,
   "next": null,
   "previous": null,
   "results":[
      {
         "id": 106,
         "name": "New Folder"
      }
   ]
}

Step 3: The Tab Endpoint

The tab endpoint is the main endpoint that returns the content for the user to consume. Given the example in Step 1 above, a GET request would be made to https://example.com/path/to/tab/endpoint with the folder, search and page query parameters. folder is the id of the selected folder (or none), search is the current search string (or none) and page is the page UUID.

Pagination is up to your API. If you return fewer items in the results array than the top level count, a 'Load More' button will be displayed until the total fetched results equal the count.

Your endpoint needs to return data that looks like:

{
   "count": 85,
   "next": null,
   "previous": "http://api.thelessonspace.com/v2/resources/?folder=&name=Language&page=1&search=",
   "results": [
      {
         "id": 1438,
         "name": "<resource name>",
         "type": "<image | zip | pdf>",
         "source": "<path to URL>",
         "thumbnail": "<base64 encoded image>"
      }
   ]
}

Using your custom library

With the above endpoints done, you can pass in your tabs endpoint (from step 1) to the Launch API by setting the top level resource_url parameter. When debugging and developing, you can also change the query parameter resource on the go.room.sh URL directly.

Enabling in-space uploads

Coming soon!