Tahoe User API
API Endpoint to retrieve user identifier data on Tahoe from a third-party system.
Use these to use an external system to retrieve user identifier information. We will be building out a more robust set of User API endpoints in the future, but we built this first set to enable a remote client to manage user enrollments, supporting the Enrollment API.
Important Note
GET List
Endpoint: /tahoe/api/v1/users/ Request Method: GET
The endpoint returns a paginated list of all users.
For our initial release, enrolled learners can be retrieved via the Enrollment API using the course id as the query parameter ( /tahoe/api/v1/enrollments/?course_id=<course-id>). This returns a collection of enrollments where each enrollment contains the learner identity. For more details, see the enrollment API GET List action.
Table 1 - Query parameters
Name | Type | Description |
email_exact | string | Email of the user to find. This will only look for exact matches in a case insensitive manner. Either one user will be returned in the list or none. This is often useful do check whether a learner have registered with this exact email. |
Response
The top level response contains pagination data, which can be used to page through the list responses.
Table 2 - Top Level Response Keys
Name | Description |
count | Number of total records retrieved |
next | Link to the next page of results. Null if no next page |
previous | Link to the previous page of results. Null if no previous page |
results | List of enrollment data. See the next table |
Table 3 - Results element values
Name | Description |
id | Unique user id (long) |
username | User’s username as the user entered during registration |
fullname | User’s full name as the user entered during registration |
User’s email address |
Example cURL command
curl -X GET \ https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/users/ \ -H 'Accept: */*' \ -H 'Authorization: Token <insert token here> \ -H 'Cache-Control: no-cache'
Example response
{ "count": 15, "next": null, "previous": null, "results": [ { "id": 1766, "username": "bsmith", "fullname": "Bucephalus Smith", "email": "bsmith@example.com" }, { "id": 3913, "username": "Delia Adams", "fullname": "dadams", "email": "delia.adams@example.com" }, ... ] }
Example cURL command with email_exact
curl -X GET \ https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/users/?email_exact=jack@turner.org.uk \ -H 'Accept: */*' \ -H 'Authorization: Token <insert token here> \ -H 'Cache-Control: no-cache'
Example response for known email
When using email_exact with an existing email a list containing one user will be returned:
{ "count": 1, "next": null, "previous": null, "results": [ { "id": 7870, "username": "jackturner", "fullname": "Jack Turner", "email": "jack@turner.org.uk" } ] }
Example response for non-existent email_exact
If no email was found with email_exact an empty list will be returned with a HTTP status code of 200:
{ "count": 0, "next": null, "previous": null, "results": [] }
GET Detail
Endpoint: /tahoe/api/v1/users/<user id>/ Request Method: GET
This returns the detail data for a single user. The fields are the same as in Table 3 above.
Example cURL command
curl -X GET \ https://<your-site-name>.tahoe.appsembler.com/tahoe/api/v1/users/1766/ \ -H 'Accept: */*' \ -H 'Authorization: Token <insert token here> \ -H 'Cache-Control: no-cache'
Example response
{ "id": 1766, "username": "bsmith", "fullname": "Bucephalus Smith", "email": "bsmith@example.com" }