@universis/eduapi

An implementation of 1EdTech EduAPI for Universis Project.

Read more about the 1EdTech EduAPI specification https://www.imsglobal.org/spec/eduapi/v1p0.

This package provides the necessary components to integrate with the 1EdTech EduAPI, allowing for seamless communication and data exchange between the Universis platform and external educational tools and services.

Universis Edu-API Standalone Service

Initialize the Edu-API Service

To use the @universis/eduapi in a standalone mode, you can run the following command:

npx @universis/eduapi --init --project-dir eduapi-app

This command initializes a new project directory named eduapi-app with the necessary configuration files and structure to run the EduAPI service independently. Note: The folder should be empty or non-existent before running the command.

--init command takes also --project-dir argument to specify the project directory. If not provided, it will use the current working directory.

Usage: npx @universis/eduapi [options]
Options:
  --help, -h                Show help
  --init, -i                Initialize the project
  --project-dir <directory> Project directory (default: current directory)
  --skip-install, -s        Skip installation of dependencies
  --db                      Database type (sqlite, mysql, postgres, mssql, oracle)

The --skip-install option allows you to skip the installation of dependencies if you prefer to manage them manually.

The --db option allows you to specify the database type for the project. Supported options are sqlite, mysql, postgres, mssql, and oracle. If not specified, it will default to sqlite.

Run the Edu-API Service

After running the command, navigate to the project directory and install the dependencies:

cd eduapi-app

and start the service using the following command:

npm start

The service will start and listen for incoming requests on the default port (usually 3000). You can configure the port using command line or the PORT environment variable if needed.

npm start -- --port 4000

You can also configure the address to listen on all network interfaces by using the --host option:

npm start -- --host 0.0.0.0

Edu-API OData Service

The Universis Edu-API exposes an OData service that allows clients to interact with the EduAPI resources using standard OData protocols. The service supports CRUD operations and provides a RESTful interface for accessing educational data.

Read more about the OData protocol https://www.odata.org/.

The OData service is accessible at the /ims/eduapi/service/ endpoint of the Edu-API service. For example, if the Edu-API service is running on http://localhost:3000, the OData service can be accessed at http://localhost:3000/ims/eduapi/service/.

It uses OAuth 2.0 for authentication and authorization, ensuring secure access to the resources. Clients must obtain an access token from the Universis authentication server and include it in the Authorization header of their requests.

A sample request to the OData service might look like this:

GET /ims/eduapi/service/CollectionTemplates HTTP/1.1
Host: localhost:3000
Authorization: Bearer <access_token>

where <access_token> is a valid OAuth 2.0 access token obtained from an OAuth 2.0 authorization server. The <access_token> should have http://purl.1edtech.org/spec/eduapi/v1p0/scope/core.admin scope to access the resources. http://purl.1edtech.org/spec/eduapi/v1p0/scope/core.admin scope is an extension of the http://purl.1edtech.org/spec/eduapi/v1p0/scope/core.readonly scope, which is required for accessing the Edu-API resources based on the 1EdTech EduAPI specification.

Read more about the Universis Edu-API OData service here

Configuration

<project dir>/config/app.json file contains the configuration for the Edu-API service. You can modify this file to change the settings according to your requirements.

{
  "$schema": "https://themost-framework.github.io/express/schemas/applicationConfiguration.json",
  "settings": {
    "schema": {
      "loaders": [
        {
          "loaderType": "@universis/webhooks#SchemaLoader"
        },
        {
          "loaderType": "@universis/eduapi#EduapiSchemaLoader"
        }
      ]
    },
    "api": {
      "origin": "http://localhost:3000"
    },
    "i18n": {
      "locales": [
        "en"
      ],
      "defaultLocale": "en"
    },
    "auth": {
      "unattendedExecutionAccount": "759b43b705380bd2ab842c4a",
      "issuer_uri": "https://login.universis.io/auth/realms/universis/"
    },
    "crypto": {
      "algorithm": "aes256",
      "key": "ff341936ba53e8ec9debce589cf72a470a9f3b0feef47962c58cad714f2ef72da1a2175b466f607a3f6c89038c465502663284c63c681e66794a2b7ba891ebe9"
    }
  },
  "adapterTypes": [
    {
      "name": "postgres",
      "invariantName": "postgres",
      "type": "@themost/pg"
    },
    {
      "name": "sqlite",
      "invariantName": "sqlite",
      "type": "@themost/sqlite"
    }
  ],
  "adapters": [
    {
      "name": "production",
      "default": true,
      "invariantName": "postgres",
      "options": {
        "host": "localhost",
        "post": 5432,
        "user": "user",
        "password": "password",
        "database": "eduapi"
      }
    },
    {
      "name": "development",
      "default": false,
      "invariantName": "sqlite",
      "options": {
        "database": ".db/eduapi.db"
      }
    }
  ]
}

If you are using a database other than SQLite, you can modify the adapters section to configure the appropriate database connection settings.

Integrate the Edu-API into Universis API Server

Install the @universis/eduapi package as a dependency in your Universis API Server project:

npm install @universis/eduapi

and register the EduapiService under services section of application configuration.

{
  "services": [
    {
        "serviceType": "@universis/eduapi#EduapiService"
    }
  ]
}

Include EduapiSchemaLoader into settings/schema/loaders:

{
    "settings": {
        "schema": {
            "loaders": [
                {
                    "loaderType": "@universis/eduapi#EduapiSchemaLoader"
                }
            ]
        }
    }
}

and finally modify the settings/universis/eduapi section to configure the EduAPI service:

{
    "settings": {
        "universis": {
          "eduapi": {
            "extends": "node_modules/@universis/eduapi/dist/config/app.json",
            "settings": {
              "api": {
                "origin": "http://api.example.com/"
              },
              "auth": {
                "unattendedExecutionAccount": "759b43b705380bd2ab842c4a",
                "issuer_uri": "https://login.example.com/users/realms/universis/"
              }
            },
            "adapterTypes": [
              {
                "name": "MSSQL Data Adapter",
                "invariantName": "mssql",
                "type": "@themost/mssql/n"
              }
            ],
            "adapters": [
              {
                "name": "eduapi+development",
                "invariantName": "mssql",
                "options": {
                  "server": "localhost",
                  "port": 4433,
                  "user": "user",
                  "password": "password",
                  "database": "eduapi",
                  "requestTimeout": 30000
                }
              }
            ]
          }
        }
    }
}

The above configuration extends the default configuration of the Edu-API service and sets up the service with the necessary settings, including the API origin, authentication details, and database adapter configuration. Modify the database connection settings according to your environment and requirements.