| Table of Contents |
|---|
Introduction
The provisioning API is an admin-only API used to create users and push synchronisations in MyTimetable. This API can be used in your user provisioning processes to support an push synchronisation 'opt-out' scenario. The API is supported from MyTimetable version 3.0, and only supports JSON output and form-encoded input.
User resources
/users
Method: GET
Description: Query all known usernames.
...
| Code Block | ||
|---|---|---|
| ||
{
"users": [
"alice@example.org",
"bob@example.org",
"carol@example.org"
]
} |
/users/{username}
Method: GET
Description: Query a specific user.
...
| Code Block | ||
|---|---|---|
| ||
$base_url/api/v0/users/alice@example.org |
Example response body
| Info |
|---|
Please note the |
| Code Block | ||
|---|---|---|
| ||
{
"username": "alice@example.org",
"displayName": "Alice",
"locale": "nl",
"attributes": [
{
"name": "urn:mace:dir:attribute-def:displayName",
"values": [
"Alice"
]
},
{
"name": "urn:mace:dir:attribute-def:mail",
"values": [
"alice@example.org"
]
},
{
"name": "urn:mace:dir:attribute-def:eduPersonAffiliation",
"values": [
"member",
"student"
]
},
{
"name": "urn:mace:dir:attribute-def:eduPersonPrincipalName",
"values": [
"alice@example.org"
]
}
],
"roles": [
"ROLE_MEMBER",
"ROLE_STUDENT"
]
} |
...
200 (OK), 404 (Not Found) if the user does not exist
/users (MyTimetable 2019.16+)
Method: POST
Description: Creates a user with the specified username.
...
201 (Created) if the user is created, 400 (Bad Request) if input validation fails, 409 (Conflict) if a user with the given username already exists
/users/{username}
Method: PUT
Description: Ensures a user with the specified username and properties exists.
...
| Name | Description | Default value |
username(required) | The username for which a user profile should be created if it doesn't exist already. | - |
Request body form values (MyTimetable 2019.16+)
| Info | ||
|---|---|---|
| ||
If no request body is sent, the following behaviour is used:
If a request body is sent, the following behaviour is used:
|
...
- If no request body is sent: 204 No Content
- If a request body is sent: 201 Created (user newly created), 200 OK (user updated), or 400 (Bad Request) if input validation fails
/users/{username}
Method: DELETE
Description: Deletes the user profile with the specified username if it exists.
...
Example response body: none (status code 204 indicates success; 404 indicates user not found)
/users/{username}/synchronizations
Method: GET
Description: Query all synchronizations for a user.
...
| Code Block | ||
|---|---|---|
| ||
{
"synchronizations": [
{
"id": 1,
"type": "ews",
"username": "alice",
"description": "alice@bob.test",
"enabled": true,
"status": "OK",
"lastResync": 1355320800000
}
]
} |
/users/{username}/synchronizations
Method: DELETE
Description: Delete all synchronizations for a user.
...
Example response body: none (status code 204 indicates success)
/users/{username}/synchronizations/{type}
Method: DELETE
Description: Delete synchronizations of a certain type for a certain user.
...
Example response body: none (status code 204 indicates success; 404 indicates no synchronizations found; 422 indicates invalid synchronisation type)
Synchronization resources
/synchronizations
Method: GET
Description: Query all synchronizations.
...
| Code Block | ||
|---|---|---|
| ||
{
"synchronizations": [
{
"id": 1,
"type": "o365",
"username": "alice",
"description": "alice@bob.test",
"enabled": true,
"status": "OK",
"lastResync": 1355320800000
},
{
"id": 1,
"type": "googlecalendar",
"username": "bob",
"description": "bob@google.test",
"enabled": true,
"status": "OK",
"lastResync": 1355320800000
}
]
} |
/synchronizations
Method: PUT
Description: Sets up a synchronization with a user's external calendar.
...
Response code: 200 OK, 422 Unprocessable Entity (username does not exist or synchronization type is not known), 550 Permission Denied (access not granted to mailbox)
/synchronizations/{id}
Method: DELETE
Description: Deletes the synchronization with the specified id.
...
Example response body: none (status code 204 indicates success; 404 indicates synchronization not found)
Sample usage
If you want to create a large number of synchronisations, create a text file with the username and email address of the users. Then you can run the following shell script to create the users:
...