API Reference¶

interface ID2LAppContext¶

Interface for an application context object that a client application uses to create an application-specific calling context for use with a Learning Framework service.

To retrieve the default library-provided implementation of an application context, the client should invoke createSecurityContext on the app context factory class.

New in version 1.0: Initial version of the PHP client library, compatible with LMS v9.4.1.

createUrlForAuthentication($host, $port, $resultUri)¶

Retrieve a URL the client can use to initiate the authentication process with the back-end service.

Parameters

• host (string) – Host name for the back-end service.

• port (string) – Port the service uses for route requests.

• resultUri (string) – Client-application-handled callback URI.

Returns

URL the client can pass to a web control to initiate user authentication.

Return type

String.

The client application will use the URL retrieved from this method by passing it to a web control or browser to let the user authenticate with the back-end service. The resultUri provided to this call is a callback URI that the client application will handle: when the back-end service finishes the user-auth process, it will redirect back to this URI, including the User ID and User Key tokens as quoted parameters.

createUserContext($host, $port, $encryptOperations, $userId=null, $userKey=null, $callbackUri=null)¶

Build a new authenticated-user context the client application can use to create decorated URLs for invoking routes on the back-end service API.

Parameters

• host (string) – Host name for the back-end service.

• port (string) – Port the service uses for route requests.

• encryptOperations (boolean) – If true, build context with HTTPS; otherwise, use HTTP.

• userId (string) – (Optional, null default) Service-provided ID for user.

• UserKey (string) – (Optional, null default) Service-provided Key for user, to sign with.

• callbackUri (string) – (Optional, null default) Entire result URI service sent back with redirect after user auth.

Returns

A new user context for creating user-authenticated URLs for API calls.

Return type

Object implementing ID2LUserContext.

An application context instance can create a user context in several modes:

• If the client application already knows an authenticated user context’s state (host, port, user ID, user Key) then it can rebuild a user context for making authenticated calls.

• If this application context implementation has just initiated the auth process with the back-end service, and now has a result URI to handle, the caller can provide that result URI and this method can parse the needed user context state out of it to build a new user context.

• If the caller wants to use one of the API routes that doesn’t require an authenticated calling user context, it can leave userId, userKey, and callbackUri parameters as null to build a “default user” context.

interface ID2LUserContext¶

Interface for a user context object that a client application uses to craft URLs for calling REST API routes, signalling the authenticated calling user context.

To retrieve an implementation, the client should invoke createUserContext on a concrete application context instance.

New in version 1.0: Initial version of the PHP client library, compatible with LMS v9.4.1.

createAuthenticatedUrl($path, $httpMethod)¶

Retrieve an appropriately decorated URI for invoking a REST route on the back-end service.

Parameters

• path (string) – REST route for the action to invoke.

• httpMethod (string) – HTTP method to use with the route for the action (DELETE, GET, POST, or PUT)

Returns

Decorated URI usable to invoke the REST API action for the method and path.

Return type

String.

calcualteServerSkewFromResponse($responseBody)¶

Calculate the clock skew between the local clock and the back-end service clock, based on an HTTP response body sent by the service.

Parameters

• responseBody (string) – HTTP response body for the timestamp out of range messaged response.

Returns

True if this method successfully recalculates the clock skew; otherwise, false.

Return type

Boolean.

If the back-end service sends back a 403 with the timestamp out of range message, the client application can use this method to re-calculate the user context’s cached server skew value.

handleResult($response, $httpCode, $contentType)¶

Interpret an HTTP response from the back-end service in response to an API call.

Parameters

• response (string) – Response body sent by the back-end service in response to a Learning Framework API call.

• httpCode (string) – HTTP code associated with the response (i.e. 200, 403, etc).

• contentType (string) – Response content-type.

Returns

Numeric constant the caller can use to determine what the next action might be.

Return type

Integer.

This method does two things:

• Given a response from the back-end service, it can do a simple parse and return a numeric value (one of the RESULT_* constant values in the D2LUserContext default implementation) indicating what the caller might need to do next (re-authenticate the user, verify that the user has permissions to attempt the action taken, and so forth).

  Most commonly, applications will minimally want to check for RESULT_OKAY in order to proceed with interpreting result data sent back by the API call.

• If the response from the back-end service indicates that the service’s clock offset is outside an allowable range, this method re-calculates the clock offset and saves it in the user context’s state.

getHostName()¶

Returns

Back-end service’s host name for this calling user context.

Return type

String.

getPort()¶

Returns

Port that the back-end service exposes for API calls.

Return type

String.

getUserId()¶

Returns

Service-provided User ID for this calling user context.

Return type

String.

getUserKey()¶

Returns

Service-provided User Key for this calling user context.

Return type

String.

getServerSkewSeconds()¶

Returns

Currently known time-skew between the local and back-end service clocks.

Return type

Integer.

setServerSkewSeconds($seconds)¶

Parameters

• seconds (integer) – New time-skew between local and back-end service clocks, in seconds.

class D2LAppContextFactory¶

Factory class to build default application context implementation instances.

New in version 1.0: Initial version of the PHP client library, compatible with LMS v9.4.1.

createSecurityContext($appId, $appKey)¶

Build and pass back a new calling application context.

Parameters

• appId (string) – Application ID, as provided by the Brightspace Manage Extensibility tool.

• appKey (string) – Application Key for signing, as provided by the Brightspace Manage Extensibility tool.

Returns

A new application context for creating calling user contexts.

Return type

Object implementing ID2LAppContext.

class D2LUserContext¶

The relevant elements of this default ID2LUserContext implementation in the public API are the various RESULT_* reference constants for mapping API results to generic result types. Non-default user context implementations should also provide these constant values.

New in version 1.0: Initial version of the PHP client library, compatible with LMS v9.4.1.

constant RESULT_UNKNOWN¶

No result can be identified; also useful as an uninitialized value.

constant RESULT_OKAY¶

Server has provided a result 200 OK response.

constant RESULT_INVALID_SIG¶

Invalid signature or context ID (app or user); typically this should prompt the client application to attempt re-authentication.

constant RESULT_INVALID_TIMESTAMP¶

Client application’s API call had a timestamp outside the validity window (the local clock has skewed too far from the service’s clock). The handleResult method should automatically correct the state of the user context to adjust for the skew, so the client application should re-try the same API call.

constant RESULT_NO_PERMISSION¶

Request API action is not allowed; typically the client application should inform the user, and perhaps direct the user to request different permissions from the service administrator.