Skip to content

endpoints.md

Latest commit

 

History

History
67 lines (48 loc) · 6.65 KB

endpoints.md

File metadata and controls

67 lines (48 loc) · 6.65 KB

<- Back to Index

HTTP Endpoints

The HTTP methods that are LRS-specific are given in the xAPI spec. Requests to the LRS (which are denoted by the xapi path prefix) must contain a Base64 encoded, colon-separated public and secret API key pair in the Authorization field of the header. For example (assuming http://example is the URL body), http://example.org/xapi/statements is the URL at which the user inserts and queries xAPI statements; other URLs are used to insert and query documents, agents, and activities.

Admin Account and Credential Routes

In addition to the LRS HTTP methods, the SQL LRS supports methods for admin account creation, login, and use, as well as routes used to create and use API ; these methods are denoted by the admin path prefix.

The following examples use http://example.org as the URL body. All methods return 200 OK on success. All routes except for account/login and admin/env must contain a JSON Web Token (JWT), generated by account creation or login, in the Authorization header in the form of Bearer [JWT]; if the JWT is expired or invalid a 401 UNAUTHORIZED is returned. All methods also require that the request body be a JSON object, though the permitted values depend on the route; invalid request bodies will result a 400 BAD REQUEST error. If an error is encountered, these routes return a JSON object in the body like the following:

{
    "error": "[error message]"
}

Admin Account Routes

  • POST http://example.org/admin/account/login: Log into an existing account. The request body must be a JSON object that contains username and password strings. These must conform to the following requirements:
    • username must be a minimum of 7 characters.
    • password must be a minimum of 10 characters.
    • password must contain at least one lower case character.
    • password must contain at least one upper case character.
    • password must contain at least one numeric character.
    • password must contain at least one of the following special characters: !@#$%^&*_-+=?.

The response body contains a newly generated JSON Web Token (JWT) on success. A 401 UNAUTHORIZED status code is returned if the credentials are incorrect.

  • POST http://example.org/admin/account/logout: Log out of the current account. This will revoke any unexpired JWTs associated with the user. (NOTE: This endpoint will return a 400 BAD REQUEST error if LRSQL_JWT_NO_VAL is set to true.)
  • GET http://example.org/admin/account/renew: Renew the current account's login session by issuing a new JWT. For a given JWT, the renewal is only granted if the current time is less than the ref timestamp (which is determined by LRSQL_JWT_REFRESH_EXP_TIME).
  • POST http://example.org/admin/account/create: Create a new admin account. The request body must be a JSON object that contains username and password strings. The endpoint returns a JSON object with the ID (UUID) of the newly created user on success, and returns a 409 CONFLICT if the account already exists.
  • DELETE http://example.org/admin/account: Delete an existing account. The JSON request body must contain a UUID account-id value. The endpoint returns a JSON object with the ID of the deleted account on success and returns a 404 NOT FOUND error if the account does not exist.
  • GET http://example.org/admin/account: Return an array of all admin accounts in the system on success.
  • GET http://example.org/admin/me: Returns the currently authenticated admin accounts on success.
  • GET http://example.org/admin/verify: Returns a 204 No Content response, without a body, on success (the success conditions are the same as the /admin/me endpoint).

Admin Credential Routes

  • POST http://example.org/admin/creds: Create a new credential pair, with the specified scope values given by the scopes property in the request body.
  • PUT http://example.org/admin/creds: Update an existing credential pair, given by api-key and secret-key properties in the request body, with the new scopes given by the scopes property.
  • GET http://example.org/admin/creds: Read all credential pairs and their associated scopes for a particular account (denoted by the JWT).
  • DELETE http://example.org/admin/creds: Delete an existing credential pair, given by the api-key and secret-key properties in the request body, as well as any associated scopes.

Statement CSV Download

  • GET http://example.org/admin/csv/auth: Return a one-time JWT for use for /admin/csv, used in order to use the latter endpoint as a download attribute for HTML anchor tags and authenticate without headers.
  • GET http://example.org/admin/csv: Download statements in the LRS as a CSV filestream. This endpoint accepts the statement query parameters defined in the xAPI spec, but allows two additional parameters: the one-time JWT token string and the URL-encoded property-path vector strings.

Misc Admin Routes

  • GET http://example.org/admin/env: Get select environment variables about the configuration which may aid in client-side operations.
  • GET http://example.org/admin/openapi: Get an OpenAPI JSON spec of the endpoint API, which can then be visualized using an OpenAPI viewer like Swagger.
  • GET http://example.org/admin/status: Get LRS status information, such as the number of statements in the LRS.
  • DELETE http://example.org/admin/agents: Runs a hard delete of all records of an actor, and associated records (statements, attachments, etc). Intended for privacy purposes like GDPR. Body should be a JSON object of form {"actor-ifi":<actor-ifi>}. Disabled unless the configuration variable enableAdminDeleteActor to be set to true.

Reaction Management Routes

If Reactions are enabled, the following routes can be used to manage them:

  • POST http://example.org/admin/reaction: Create a new reaction by providing a JSON ruleset and active boolean. On success returns 200 with the reactionId of the new reaction.
  • GET http://example.org/admin/reaction: List all reactions, active and inactive.
  • PUT http://example.org/admin/reaction: Given a reactionId and either a JSON ruleset or boolean active parameter, update the given reaction. On success returns 200 with the reactionId of the updated reaction. Returns 404 if the reaction is not found.
  • DELETE http://example.org/admin/reaction: Delete a reaction specified by reactionId. Returns 200 with the reactionId of the deleted reaction on success or 404 if not found.

<- Back to Index