Page Comparison

...

Code Block

language	none

{
    "users": [
        "alicealice@example.org", 
        "bobbob@example.org", 
        "carolcarol@example.org"
    ]
}

/users/{username}

Method: PUTGET

Description: Ensures Query a specific user with the specified username exists.

Parameters

Name	Description	Default value
`username`(required)	The username for which a user profile should be created if it doesn't exist alreadyto query.	-

Example request URL

Code Block

language	none

$base_url/api/v0/users/alice

...

/api/v0/users/alice@example.org

Example response body

Code Block

language	none

{
    "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"
    ]
}

Response code

200 (OK), 404 (Not Found) if the user does not exist

/users

Method: POST

Description: Creates a user with the specified username.

Parameters: none

Request body form values:

Name	Description	Default value
`username (required)`	Username of the user.	`-`
`displayName`	Display Name of the user	`-`
`locale`	Locale of the user, or empty for the default locale.	`-`
`attributes`	Attribute for the user. This form value can be set multiple times. The format used is attributeName=attributeValue. When multiple values with the same attributeName are given, all attributeValues are persisted. See example request below.	`[]`
`roles`	Roles of the user. This form value can be set multiple times.	`[]`

Request URL

Code Block

language	none

$base_url/api/v0/users

Request Accept header

application/json

Request Content-Type header

application/x-www-form-urlencoded

Example request body

Code Block

language	none

username=alice%40example.org&displayName=Alice&locale=nl&attributes=urn%3Amace%3Adir%3Aattribute-def%3AdisplayName%3DAlice&attributes=urn%3Amace%3Adir%3Aattribute-def%3AeduPersonAffiliation%3Dmember&attributes=urn%3Amace%3Adir%3Aattribute-def%3AeduPersonAffiliation%3Dstudent&attributes=urn%3Amace%3Adir%3Aattribute-def%3Amail%3Dalice%40example.org&attributes=urn%3Amace%3Adir%3Aattribute-def%3AeduPersonPrincipalName%3Dalice%40example.org&roles=ROLE_MEMBER&roles=ROLE_STUDENT

Decoded example request body

Code Block

language	none

username=alice@example.org
displayName=Alice
locale=nl
attributes=urn:mace:dir:attribute-def:displayName=Alice
attributes=urn:mace:dir:attribute-def:eduPersonAffiliation=member
attributes=urn:mace:dir:attribute-def:eduPersonAffiliation=student
attributes=urn:mace:dir:attribute-def:mail=alice@example.org
attributes=urn:mace:dir:attribute-def:eduPersonPrincipalName=alice@example.org
roles=ROLE_MEMBER
roles=ROLE_STUDENT

Example response Body

Code Block

language	none

{
    "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"
    ]
}

Response code

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.

Parameters

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

Info

title	Behaviour

If no request body is sent, the following behaviour is used:

User does not exist: user is created
User already exists: nothing is changed
In either case, no response body is returned

If a request body is sent, the following behaviour is used:

User does not exist: user is created with the properties set as requested via the request body (otherwise they are not set)
User already exists: the properties of the user are updated with the properties set as requested via the request body (otherwise they are unchanged)
In either case, the user is returned as the response body

Name	Description	Default value
`displayName`	Display name of the user	`-`
`locale`	Locale of the user, or empty for the default locale.	`-`
`attributes`	Attribute for the user. This form value can be set multiple times. The format used is attributeName=attributeValue. When multiple values with the same attributeName are given, all attributeValues are persisted. See example request below.	`[]`
`roles`	Roles of the user. This form value can be set multiple times.	`[]`

Request URL

Code Block

language	none

$base_url/api/v0/users/alice@example.org

Request Accept header

application/json

Request Content-Type header

application/x-www-form-urlencoded

Example request body

Code Block

language	none

displayName=Alice&locale=nl&attributes=urn%3Amace%3Adir%3Aattribute-def%3AdisplayName%3DAlice&attributes=urn%3Amace%3Adir%3Aattribute-def%3AeduPersonAffiliation%3Dmember&attributes=urn%3Amace%3Adir%3Aattribute-def%3AeduPersonAffiliation%3Dstudent&attributes=urn%3Amace%3Adir%3Aattribute-def%3Amail%3Dalice%40example.org&attributes=urn%3Amace%3Adir%3Aattribute-def%3AeduPersonPrincipalName%3Dalice%40example.org&roles=ROLE_MEMBER&roles=ROLE_STUDENT

Decoded example request body

Code Block

language	none

displayName=Alice
locale=nl
attributes=urn:mace:dir:attribute-def:displayName=Alice
attributes=urn:mace:dir:attribute-def:eduPersonAffiliation=member
attributes=urn:mace:dir:attribute-def:eduPersonAffiliation=student
attributes=urn:mace:dir:attribute-def:mail=alice@example.org
attributes=urn:mace:dir:attribute-def:eduPersonPrincipalName=alice@example.org
roles=ROLE_MEMBER
roles=ROLE_STUDENT

Example response body

If no request body is sent, no response body is returned.

If a request body is sent, the user is returned as the response body:

Code Block

language	none

{
    "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"
    ]
}

Response code

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.

...

Code Block

language	none

username=alicealice@example.org&type=ews&provisioning_smtpAddress=alice@examplealice@bob.orgtest

Example response body:

Code Block

language	none

{
    "synchronization":
        {
            "id": 1, 
            "type": "ews", 
            "username": "alicealice@example.org",
			"description": "alice@bob.test",
            "enabled": true,
		    "status": "OK",
            "lastResync": 1355320800000
        }
}

...

Versions Compared

Old Version 19

New Version 20

Key

/users/{username}

/users

/users/{username}

/users/{username}