Introduction

this document describes the mandatory endpoint to implement a REST provisioning API for OBM.

The API scope is, for the first delivery deadline :

CRUD of OBM users CRUD of OBM groups R of OBM profiles

The API should be batchable: in a first step we describe the operations to be done, and in a second step we commit those operations.

Namings

In this document we take /provisioning/{apiVersion}/{domainUUID} as the base URI of REST end points. It will be called {baseURI} in the rest of the document. The notation {batchId} represents a unique batch number. The notation {userId} represents a unique user number. The notation {groupId} represents a unique group number. The notation {apiVersion} represents a string linking to the version of the API that the client want to use (eg. "v1") The notation {domainUUID} represents the domain universally unique ID we work on.

Start of batch

The objective of this end point is to get a new unique batch number. The life time of a batch and the rules for concurrent batches and batch conflicts are to be defined in the complete definition of this end point (in another document).

• method: POST
• endpoint: {baseURI}/batches

Commit of the batch

The objectives of this end point is to launch the commit of the batch, which means effectively applying the operations we declared inside the batch.

• method: PUT
• endpoint: {baseURI}/batches/{batchId}

Rollback of the batch

The objective of this end point is to cancel the batch, which means forget all the operations we declared inside the batch, and destroy the batch (so {batchId} is unknown after).

• method: DELETE
• endpoint: {baseURI}/batches/{batchId}

Status of the batch

The objective of this end point is to get the actual state of the batch, and perhaps associated information. The states list is to be defined in another document.

• method: GET
• endpoint: {baseURI}/batches/{batchId}

Managing users

Creating a user

Creating a user without specifying the user unique id

The objective of this end point is to create a new user in the OBM system. It's the server's responsability to associate a unique ID to the newly created user.

• method: POST
• endpoint: {baseURI}/batches/{batchId}/users

Creating a user, specifying the user unique id

See "Creating or modifying a user"

Creating or modifying a user

The objective of this end point is to modify an already existing user, or to create a new user, providing the user unique id.

• method: PUT
• endpoint: {baseURI}/batches/{batchId}/users/{userId}

Modifying a user with partial information

The objective of this end point is to modify an already existing user, providing the user unique id. The client won't send all the information of the user, but only the fields that should be updated.

• method: PATCH
• endpoint: {baseURI}/batches/{batchId}/users/{userId}

Deleting a user

The objective of this end point is to remove the user from the OBM system.

• method: DELETE
• endpoint: {baseURI}/batches/{batchId}/users/{userId}

Getting a user

The objective of this end point is to get all information of a user.

• method: GET
• endpoint: {baseURI}/users/{userId}

Managing groups

Creating a group without specifying the user unique id

The objective of this end point is to create a new group in the OBM system. It's the server's responsability to associate a unique ID to the newly created group.

• method: POST
• endpoint: {baseURI}/batches/{batchId}/groups

Creating a group, specifying the group unique id

See "Creating or modifying a group"

Creating or modifying a group

The objective of this end point is to modify an already existing group, or to create a new group, providing the group unique id.

• method: PUT
• endpoint: {baseURI}/batches/{batchId}/groups/{groupId}

Modifying a group with partial information

The objective of this end point is to modify an already existing group.

• method: PUT
• endpoint: {baseURI}/batches/{batchId}/groups/{groupId}

Deleting a group

The objective of this end point is to remove the group from the OBM system.

• method: DELETE
• endpoint: {baseURI}/batches/{batchId}/groups/{groupId}

Assigning a user list to a group

The objective of this end point is to set the list of the users belonging to the group.

• method: PUT
• endpoint: {baseURI}/batches/{batchId}/groups/{groupId}/users

Adding a user to a group

The objective of this end point is to add a user to the list of the users belonging to the group.

• method: PUT
• endpoint: {baseURI}/batches/{batchId}/groups/{groupId}/users/{userId}

Removing a user from a group

The objective of this end point is to remove a user from the list of the users belonging to the group.

• method: DELETE
• endpoint: {baseURI}/batches/{batchId}/groups/{groupId}/users/{userId}

Getting a group

The objective of this end point is to get all information of a group.

• method: GET
• endpoint: {baseURI}/groups/{groupId}

Getting the members of a group

The objective of this end point is to get the list of the users belonging to the group.

• method: GET
• endpoint: {baseURI}/batches/{batchId}/groups/{groupId}/users

Managing profiles

Listing profiles

The objective of this end point is to get the list of all existing profiles.

Note: we need this end point for a client project.

• method: GET
• endpoint: {baseURI}/profiles/

Addressbooks

Create or modify an addressbook

The objective of this end point is to create or update an addressbook in the OBM system.

• method: POST
• endpoint: {baseURI}/batches/{batchId}/addressbooks/{ownerEmail}
• payload: {name: "new book", role: "$ROLE", reference: { value: "ref1", origin: "myTool" } }

Notes:

• $ROLE: there are three kinds of addressbook role in OBM, the value given to the field "role" above must be one of: PRIMARY, COLLECTED, CUSTOM
• The "reference" field is optional, it is useful to later modify the addressbook's name or create a contact in a specific addressbook.
• You cannot update an addressbook if you have no "reference" on it.

Remove an addressbook

Not yet implemented.