Module verbs

xapi_rs::resources

Module verbs 

Source
Expand description

§Verbs extension

This is a LARS specific xAPI resource extension that allows authorized users to access and manipulate Verb accessible resources.

The Extension end-point base URL is <LRS_EXTERNAL_URL>/extensions/verbs where LRS_EXTERNAL_URL is the configured environment variable representing the external host address of the running server instance. For brevity purposes this “base” will be assumed to prefix the segment(s) associated to a handler. So if /foo is given, the full URL to invoke the action will be <LRS_EXTERNAL_URL>/extensions/verbs/foo.

§Authentication & authorization considerations

Only authenticated Users are allowed to invoke this Extension’s actions. In other words, it is only operable in non-legacy modes of operations.

For now there’s no specific Permission for using this Extension. Any authenticated User is also authorized to use it.

§Types

Three publicly visible data structures are used with this extension:

  • Verb: The publicly visible Verb resource (from the data module) with its id and display fields described in the specification.

  • VerbUI: A slim representation of a Verb, suitable for GUI navigation and pagination, and consisting of 3 fields:

    • rid: The resource identifier.
    • iri: The IRI identifier of the corresponding Verb.
    • display: Text corresponding to a specific language tag if present in the corresponding Verb display language map.

  • Aggregates: A structure containing three aggregates relevant to the Verbs collection:

    • min: Minimum row identifier.
    • max: Maximum row identifier.
    • count: Number of rows.

For now a Verb once created cannot be removed, nor can its IRI Identifier be changed. In the future i may allow deletion of unused verbs by a user w/ an appropriate permission.

§Handlers

§Create new Verb (POST /)

Body: Valid JSON object representation of a Verb.

Status codes:

  • 200 OK - Resource created.
  • 400 Bad Request - The request’s body is empty, is not a valid JSON object, does not translate to a valid Verb with at least one non-null display entry, or a Verb with the same IRI already exists.
  • 401 Unauthorized - User is not allowed.
  • 500 Internal Server Error - An unexpected error occurred.

§Update existing Verb

Update an existing Verb by completely replacing its display property. In other words if the old one had an entry for a language tagged as en-AU but the new one doesn’t then if the call is successful, there will be no display entry for en-AU in the Verb in question.

IMPORTANT - This call is subject to the same xAPI Concurrency Control requirements.

§Alternative #1 - By IRI (PUT /)

Body: Valid JSON object representation of a Verb.

Status codes:

  • 204 No Content - Resource updated + ETag included in the Response.
  • 400 Bad Request - IRI or JSON representation were invalid or an ID mismatch was detected.
  • 401 Unauthorized - User is not allowed.
  • 404 Not Found - Unknown Verb.
  • 409 Conflict - If-Match, or If-None-Match pre-conditions were not included in the request.
  • 412 Precondition Failed - The ETag of the existing Verb fails the If-Match, If-None-Match pre-conditions.
  • 500 Internal Server Error - An unexpected error occurred.
§Alternative #2 - By RID (PUT /<rid>)

Similar to the 1st alternative except it relies on the rid of the resource as a path segment.

§Patch existing Verb

Like PUT these calls allow modifying an existing Verb. However in this case, the new display property will be the result of merging the old with the new one with entries from the new one replacing those from the old ones for matching language tags.

IMPORTANT - This call is subject to the same xAPI Concurrency Control requirements.

§Alternative #1 - By IRI (PATCH /)

Body: Valid JSON object representation of a Verb.

Status codes:

  • 204 No Content - Resource updated + ETag included in the Response.
  • 400 Bad Request - IRI or JSON representation were invalid or an ID mismatch was detected.
  • 401 Unauthorized - User is not allowed.
  • 404 Not Found - Unknown Verb.
  • 409 Conflict - If-Match, or If-None-Match pre-conditions were not included in the request.
  • 412 Precondition Failed - The ETag of the existing Verb fails the If-Match, If-None-Match pre-conditions.
  • 500 Internal Server Error - An unexpected error occurred.
§Alternative #2 - By RID (PATCH /<rid>)

Similar to the 1st alternative except it relies on the rid of the resource as a path segment.

§Get one Verb

§Alternative #1 - By IRI (GET /?<iri>)

IMPORTANT - LaRS allows using the last segment of certain Vocabulary verbs as an alias. For those Verbs using that short alias instead of the full IRI is allowed in this context. For example using answered instead of http://adlnet.gov/expapi/verbs/answered is acceptable.

Parameters:

  • iri (required): An IRI (or an alias) representing an existing Verb identifier.

Response: JSON object representation of a Verb.

Status codes:

  • 200 OK.
  • 400 Bad Request - Invalid IRI.
  • 401 Unauthorized - User is not allowed.
  • 404 Not Found - Unknown Verb.
  • 500 Internal Server Error - An unexpected error occurred.
§Alternative #2 - By RID (GET /<rid>)

Similar to the 1st alternative except it relies on the rid of the resource as a path segment.

§Get Verb aggregates (GET /aggregates)

Status codes:

  • 200 OK.
  • 400 Bad Request - Invalid parameter(s).
  • 500 Internal Server Error - An unexpected error occurred.

Response: JSON object representation of an Aggregates.

§Get some Verbs (GET /?<language>&<start>&<count>&<asc>)

Parameters:

  • language (optional): A valid language tag string. If missing, a default value will be used.
  • start (optional): The starting rid value to use when slicing the resource collection. If missing, a default value of 0 will be used.
  • count (optional): Positive integer, greater or equal to 10 but less than 101 limiting the number of items to return. If missing, a default of 50 will be used.
  • asc (optional): Boolean flag indicating if the sort order of the returned VerbUI items’ rid values is ascending (true) or descending (false). If missing, the default of true will be used.

Status codes:

  • 200 OK.
  • 400 Bad Request - Invalid parameter(s).
  • 500 Internal Server Error - An unexpected error occurred.

Response: Potentially empty JSON array representation of the VerbUI instances. The display property of each VerbUI will be populated from the value in display from the corresponding Verb resource mapped by the given language tag.

Structs§

VerbUI
Simplified Verb representation.