OBM Provisioning API

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.

Contacts

Create or modify a contact

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

  • method: POST
  • content-type: plain/text
  • endpoint: {baseURI}/batches/{batchId}/contacts/{ownerEmail}
  • payload: raw VCF data

Notes:

  • The contact will be created in the ownerEmail's primary addressbook. To import it in another book, you have to specify the book's reference (see the "Addressbooks" section) as query params to the request. For instance "?addressBookRef=ref1&addressBookRefOrigin=myTool".
  • Comparing to ICS, the VCF standard has no UUID or SEQUENCE properties to help OBM to identify the created contact. The OBM's API accepts two query params to manage that, "trackingRef" for the UUID and "trackingDate" for the SEQUENCE. Be aware that using these "tracking" params with a VCF containing multiple VCARD is denied. For instance "?trackingRef=contact1&trackingDate=2016-09-02T07:51:20Z".
  • You cannot update a contact if you have not the "trackingRef" for it.

Remove a contact

Not yet implemented.

Events

Create or modify an event

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

  • method: POST
  • content-type: plain/text
  • endpoint: {baseURI}/batches/{batchId}/events/{ownerEmail}
  • payload: raw ICS data

Notes:

  • The event will be created in the ownerEmail's calendar.
  • The UUID and SEQUENCE properties are used by OBM to distinguish creation and update. If the event's UUID is already known by OBM it will try an update. An update will be performed only if the event's SEQUENCE is higher than the OBM's one.
  • An attendee of type RESOURCE will be created automatically if its email address belongs to the same domain than the calendar owner.
  • An attendee of type INDIVIDUAL will be created automatically in the COLLECTED addressbook, if its email address is unknown by the owner.

Remove an event

Not yet implemented.

 

NIKE HYPERLIVE EP