API Server¶

Ralph comes with an API server that aims to implement the Learning Record Store (LRS) specification (still a work in progress).

Getting started¶

The API server can be started up with the following command:

$ ralph runserver --backend es

The --backend (or -b) option specifies which database backend to use for LRS data storage and retrieval. See Ralph’s backends documentation for more details.

However, before you can start your API server and make requests against it, you need to set up your credentials.

Creating a credentials file¶

The credentials file is expected to be a valid JSON file. Its location is specified by the RALPH_AUTH_FILE configuration value. By default, ralph will look for the auth.json file in the application directory (see click documentation for details).

The expected format is a list of entries (JSON objects) each containing the username, the user’s bcrypt hashed+salted password and scopes they can access:

[
  {
    "username": "john.doe@example.com",
    "hash": "$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2",
    "scopes": ["example_scope"]
  },
  {
    "username": "simon.says@example.com",
    "hash": "$2b$12$yBXrzIuRIk6yaft5KUgVFOIPv0PskCCh9PXmF2t7pno.qUZ5LK0D2",
    "scopes": ["second_scope", "third_scope"]
  }
]

To create a new user credentials, Ralph’s CLI provides a dedicated command:

$ ralph auth \
    --username janedoe \
    --password supersecret \
    --scope janedoe_scope \
    -w

This command updates your credentials file with the new janedoe user.

Note that running this command requires that you installed Ralph with the CLI optional dependencies, e.g. pip install ralph-malph[cli] (which we highly recommend).

Making a GET request¶

The first request that can be answered by the ralph API server is a whoami request, which checks if the user is authenticated and returns their username and permission scopes.

Use curl to get http://localhost:8100/whoami:

$ curl http://localhost:8100/whoami
< HTTP/1.1 401 Unauthorized
< {"error":"Not authenticated"}

Send your username and password to the API server through HTTP Basic Auth:

$ curl --user john.doe@example.com:PASSWORD http://localhost:8100/whoami
< HTTP/1.1 200 OK
< {"username":"john.doe@example.com","scopes":["authenticated","example_scope"]}

Forwarding statements¶

Ralph’s API server can be configured to forward xAPI statements it receives to other LRSes.

To configure statement forwarding, you need to create a .env file in the current directory and define the RALPH_XAPI_FORWARDINGS variable or define the RALPH_XAPI_FORWARDINGS environment variable.

The value of the RALPH_XAPI_FORWARDINGS variable should be a JSON encoded list of dictionaries where each dictionary defines a forwarding configuration and consists of the following key/value pairs:

key	value type	description
`is_active`	`boolean`	Specifies whether or not this forwarding configuration should take effect.
`url`	`URL`	Specifies the endpoint URL where forwarded statements should be send.
`basic_username`	`string`	Specifies the basic auth username.
`basic_password`	`string`	Specifies the basic auth password.
`max_retries`	`number`	Specifies the number of times a failed forwarding request should be retried.
`timeout`	`number`	Specifies the duration in seconds of network inactivity leading to a timeout.

Note that for a forwarding configuration to be valid it is required that all key/value pairs are defined.

Example of a valid forwarding configuration:

RALPH_XAPI_FORWARDINGS='
[
  {
    "is_active": true,
    "url": "http://lrs1.example.com/xAPI/statements/",
    "basic_username": "admin1@example.com",
    "basic_password": "PASSWORD1",
    "max_retries": 1,
    "timeout": 5
  },
  {
    "is_active": true,
    "url": "http://lrs2.example.com/xAPI/statements/",
    "basic_username": "admin2@example.com",
    "basic_password": "PASSWORD2",
    "max_retries": 5,
    "timeout": 0.2
  }
]
'

Sentry configuration¶

Ralph provides Sentry integration to monitor its LRS server and its CLI. To activate Sentry integration, one should define the following environment variables:

RALPH_SENTRY_DSN={PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}{PATH}/{PROJECT_ID}
RALPH_EXECUTION_ENVIRONMENT=development

The Sentry DSN (Data Source Name) can be found in your project settings from Sentry application. The execution environment should reflect the environment Ralph has been deployed in (e.g. production).

You may also want to monitor the performance of Ralph by configuring the CLI and LRS traces sample rates:

RALPH_SENTRY_CLI_TRACES_SAMPLE_RATE=0.1
RALPH_SENTRY_LRS_TRACES_SAMPLE_RATE=0.3

Note that a sampling rate of 1.0 means 100% of transactions are sent to sentry and 0.1 only 10%.

If you want to lower noisy transactions (e.g. in a Kubernetes cluster), you can disable health checks related ones:

RALPH_SENTRY_IGNORE_HEALTH_CHECKS=True