Page Comparison

...

The table below describes the routes that the HTTP interface provides, all of the URLs are relative to http://www.example.org/data/xAPI where http://www.example.org is the URL of your Learning Locker instance. To access this interface, you must additionally supply your Basic Auth details with each request in the Authorization header. Your Basic Auth details can be found under Settings > Clients. Go to the xAPI HTTP interface documentation to see the rest of the xAPI routes.

Route	Description
GET /agents	Retrieves all of the agents used by a person.
PUT /agents/profile	Creates or overwrites a profile document.
POST /agents/profile	Creates or merges a profile document.
GET /agents/profile	Retrieves a single profile document or multiple profile identifiers.
DELETE /agents/profile	Deletes a single profile document.

GET /agents

This route allows you to retrieve all of the agents that are used by a single person, given one of the agents that they use via the required agent URL parameter. The request below demonstrates how this is done. A person can be created by inserting statements or using the Persona HTTP interface. Multiple agents can be associated with a person by using the Persona HTTP interface too. For more information, view the GET /agents route in the xAPI specification.

Code Block
GET http://www.example.org/data/xAPI/agents?agent=%7B%22mbox%22%3A%20%22mailto%3Atest%40example.org%22%7D Authorization: YOUR_BASIC_AUTH X-Experience-API-Version: 1.0.3

...

Code Block

HTTP/1.1 200 OK
X-Experience-API-Version: 1.0.3
Content-Type: application/json; charset=utf-8

{
  "objectType": "Person",
  "account": [],
  "mbox": ["mailto:test@example.org"],
  "mbox_sha1sum": [],
  "openid": []
}

PUT /agents/profile

This route allows you to create a single profile document if it doesn't exist or overwrite an existing profile document if it does exist. The route has 2 required URL parameters, an agent (a JSON encoded object representing the agent that the profile belongs to) and a profileId (a string representing an identifier for the profile). For more information, view the PUT /agents/profile route in the xAPI specification.

PUT Initial Profile

To PUT an initial profile, the request should be something like the request below. Notice that there is an If-None-Match header in the request below, this is to ensure that a profile document doesn't already exist before the profile document is created. Without the If-None-Match header there would be a precondition failure thrown and the response would be a 412 for the request below.

...

Code Block
HTTP/1.1 204 NO CONTENT X-Experience-API-Version: 1.0.3

GET Initial PUT Agent ETag

To retrieve the ETag for the initial profile, you need to retrieve the profile via the GET /agents/profile route. The request below demonstrates how to do this.

...

Code Block

HTTP/1.1 200 OK
X-Experience-API-Version: 1.0.3
Content-Type: application/json; charset=utf-8
ETag: "7C0791125FAB08C7EB75CC8044CFDCEA56F506958DEEE763E6608608EE76C9EE"
Last-Modified: 2017-08-31T15:16:29.709Z

{
  "key_to_remove": "value_to_remove",
  "key_to_change": "value_before_changed"
}

PUT Overwrite Profile

To PUT a profile for overwriting, the request should be something like the request below. Notice that the ETag from the previous request has been used in the If-Match header below. Without the If-Match header containing the correct ETag there would be a precondition failure thrown and the response would be a 412 for the request below. The If-Match header ensures that concurrent updates only change the existing profile document you expected to change.

...

Code Block
HTTP/1.1 204 NO CONTENT X-Experience-API-Version: 1.0.3

GET Overwritten Profile

To GET the overwritten profile, the request should be something like the request below.

...

Code Block

HTTP/1.1 200 OK
X-Experience-API-Version: 1.0.3
Content-Type: application/json; charset=utf-8
ETag: "BBB79685FA17A8450E7307710C8A79FD9C1059A0106E9F9811AF6FD18D0F0EED"
Last-Modified: 2017-08-31T15:17:29.709Z

{
  "key_to_change": "value_after_change",
  "key_to_add": "value_to_add"
}

POST /agents/profile

This route allows you to create a single profile document if it doesn't exist or merge an existing profile document if it does exist. The route allows the same URL parameters as the PUT /agents/profile route. The profile document is merged when the profile document exists, the existing profile document is a JSON encoded object, and the posted profile document is a JSON encoded object. When the two JSON encoded documents are merged, only the top-level properties are merged. The example requests below demonstrate merging profile documents. For more information, view the POST /agents/profile route in the xAPI specification.

POST Initial Profile

To POST an initial profile, the request should be something like the request below. Notice that there is an If-None-Match header in the request below, this is to ensure that a profile document doesn't already exist before the profile document is created. Without the If-None-Match header there would be a precondition failure thrown and the response would be a 412 for the request below.

...

Code Block
HTTP/1.1 204 NO CONTENT X-Experience-API-Version: 1.0.3

GET Initial POST Agent ETag

To retrieve the ETag for the initial profile, you need to retrieve the profile via the GET /agents/profile route. The request below demonstrates how to do this.

...

Code Block

HTTP/1.1 200 OK
X-Experience-API-Version: 1.0.3
Content-Type: application/json; charset=utf-8
ETag: "7C0791125FAB08C7EB75CC8044CFDCEA56F506958DEEE763E6608608EE76C9EE"
Last-Modified: 2017-08-31T15:16:29.709Z

{
  "key_to_keep": "value_to_keep",
  "key_to_change": "value_before_change"
}

POST Merge Profile

To POST a profile for merging, the request should be something like the request below. Notice that the ETag from the previous request has been used in the If-Match header below. Without the If-Match header containing the correct ETag there would be a precondition failure thrown and the response would be a 412 for the request below. The If-Match header ensures that concurrent updates only change the existing profile document you expected to change.

...

Code Block
HTTP/1.1 204 NO CONTENT X-Experience-API-Version: 1.0.3

GET Merged Profile

To GET the merged profile, the request should be something like the request below.

...

Code Block

HTTP/1.1 200 OK
X-Experience-API-Version: 1.0.3
Content-Type: application/json; charset=utf-8
ETag: "BBB79685FA17A8450E7307710C8A79FD9C1059A0106E9F9811AF6FD18D0F0EED"
Last-Modified: 2017-08-31T15:17:29.709Z

{
  "key_to_keep": "value_to_keep",
  "key_to_change": "value_after_change",
  "key_to_add": "value_to_add"
}

GET /agents/profile

This route allows you to retrieve a single profile document or multiple profile identifiers. If the profileId URL parameter is set, it will retrieve a single profile document with the profile identifier, otherwise it will retrieve many profile identifiers. For more information, view the GET /agents/profile route in the xAPI specification.

Retrieve Single Agent Document

The route allows the same URL parameters as the PUT /agents/profile route. A request to this route should be similar to the request below.

...

Code Block

HTTP/1.1 200 OK
X-Experience-API-Version: 1.0.3
Content-Type: application/json; charset=utf-8
ETag: "7C0791125FAB08C7EB75CC8044CFDCEA56F506958DEEE763E6608608EE76C9EE"
Last-Modified: 2017-08-31T15:16:29.709Z

{
  "example_key": "example_value"
}

Retrieve Many Agent Identifiers

The route allows the same URL parameters as the PUT /agents/profile route except for the profileId parameter and with the addition of the optional since parameter. The since URL parameter is an ISO timestamp that ensures only profile identifiers stored since the timestamp (exclusive) are returned. A request to this route should be similar to the request below.

...

Code Block
HTTP/1.1 200 OK X-Experience-API-Version: 1.0.3 Content-Type: application/json; charset=utf-8 ["example_profile_id"]

DELETE /agents/profile

This route allows you to delete a single profile document and allows the same URL parameters as the PUT /agents/profile route. For more information, view the DELETE /agents/profile route in the xAPI specification.

GET Agent Profile ETag

To retrieve the ETag for the agent profile, you need to retrieve the profile via the GET /agents/profile route. The request below demonstrates how to do this.

...

Code Block

HTTP/1.1 200 OK
X-Experience-API-Version: 1.0.3
Content-Type: application/json; charset=utf-8
ETag: "BBB79685FA17A8450E7307710C8A79FD9C1059A0106E9F9811AF6FD18D0F0EED"
Last-Modified: 2017-08-31T15:17:29.709Z

{
  "example_key": "example_value"
}

Delete Agent Profile

Notice that the ETag from the previous request has been used in the If-Match header below. Without the If-Match header containing the correct ETag there would be a precondition failure thrown and the response would be a 412 for the request below. The If-Match header ensures that concurrent deletes only delete the existing profile document you expected to delete.

...

Versions Compared

Old Version 4

New Version Current

Key

GET /agents

PUT /agents/profile

PUT Initial Profile

GET Initial PUT Agent ETag

PUT Overwrite Profile

GET Overwritten Profile

POST /agents/profile

POST Initial Profile

GET Initial POST Agent ETag

POST Merge Profile

GET Merged Profile

GET /agents/profile

Retrieve Single Agent Document

Retrieve Many Agent Identifiers

DELETE /agents/profile

GET Agent Profile ETag

Delete Agent Profile