Provisioning: group API

Managing Groups

Introduction

This document details the end points related to the group management of the OBM provisioning system.

The default exchange format is JSON.

Quick access menu

Namings

In this document we take /provisioning/{apiVersion}/{domainUUID} as the base URI of REST end points. It will be called {baseURI} in the document. The notation {serverBaseURL} represents the root URL of the REST server, eg http://1.2.3.4:8080/ The notation {batchId} represents a unique batch number. The notation {batchStatus} represents a batch status, issued from the batch status list. The notation {apiVersion} represents a string linking to the version of the API that the client want to use (eg. "v1") The notation {groupId} represents a unique group id. The notation {userId} represents a unique user id.

Resources used

 

Group Resource

Example:

{
  "id": "84109ac4-9979-4692-aee9-0a9ab66621ca",
  "name": "admin",
  "email": "group@domain",
  "description": "System Administrators",
  "members": { group member resource }
}

Required Properties:

Property NameValue TypeDescription
idstringThe unique id representing the group resource
namestringThe short (common) name of the group

Optional Properties:

Property NameValue TypeDescription
emailstringThe mail of the group. It is used as alias
descriptionstringThe long description of the group
membersobjectA Group member resource with the group members

Group member resource

Example:

{
  "users": [
    group user resource
  ],
  "subgroups": [
    group user resource
  ],
}

Optional Properties:

Property NameValue TypeDescription
users[]listA list of users in a group
subgroups[]listA list of subgroups in a group

 

 

Creating a group

Definition

This end point creates a new group with a server-generated group id. If you want to create a group with an existing id, use the endpoint for updating a group instead.

REST information

  • method: POST
  • uri: {baseURI}/batches/{batchId}/groups
  • query string arguments: none
  • request body: json data structure describing group properties

  • return code:

    • 201 Created if the group has been created
    • 5XX errors on errors
  • return content:

    • On success: nothing
    • On error: see "standard errors"

Modifying a group with full information

Definition

The objective of this end point is to overwrite an already existing group with a defined {groupId}.

REST information

  • method: PUT
  • uri: {baseURI}/batches/{batchId}/groups/{groupId}
  • query string arguments: none
  • request body: json data structure describing group properties

  • return code:

    • 200 Success if the group is already in existence and properties were successfully updated
    • 5XX errors on errors
  • return content:

    • On success: modified group properties object
    • On error: see "standard errors"

Modifying a group with partial information

Definition

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

REST information

  • method: PATCH
  • uri: {baseURI}/batches/{batchId}/groups/{groupId}
  • query string arguments: none
  • request body: json data structure describing changed group properties

  • return code:

    • 200 Success if patching the object was successful
    • 5XX errors on errors
  • return content:

    • On success: modified (full) group properties object
    • On error: see "standard errors"

 

 

Deleting a group

Definition

This endpoint deletes a specific group specified by the {groupId}.

REST information

  • method: DELETE
  • uri: {baseURI}/batches/{batchId}/groups/{groupId}
  • query string arguments: none
  • request body: none

  • return code:

    • 200 Success if the group was deleted
    • 404 Not Found if the groupId or batchId was not found
    • 5XX errors on errors
  • return content:

    • On success: no content
    • On error: see "standard errors"

Adding a user to a group

Definition

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

REST Information

  • method: PUT
  • uri: {baseURI}/batches/{batchId}/groups/{groupId}/users/{userId}
  • query string arguments: none
  • request body: none

  • return code:

    • 200 Success if the user was already part of the group
    • 201 Created if the user was added to the group
    • 404 Not Found if the userId, groupId or batchId was not found
    • 5XX errors on errors
  • return content:

    • On success: no content
    • On error: see "standard errors"

Assigning a user list to a group

Definition

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

REST information

  • method: PUT
  • uri: {baseURI}/batches/{batchId}/groups/{groupId}/members
  • query string arguments: none
  • request body:

    { "users": [] "subgroups": [] }

  • return code:

    • 200 Success if assigning the user list succeeded
    • 404 Not Found if the groupId or batchId was not found
    • 5XX errors on errors
  • return content:

    • On success: no content
    • On error: see "standard errors"

Removing a user from a group

Definition

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

REST information

  • method: DELETE
  • uri: {baseURI}/batches/{batchId}/groups/{groupId}/users/{userId}
  • query string arguments: none
  • request body: none

  • return code:

    • 200 Success if the user was removed from the group
    • 404 Not Found if the userId, groupId or batchId was not found
    • 5XX errors on errors
  • return content:

    • On success: no content
    • On error: see "standard errors"

Adding a subgroup to a group

Definition

The objective of this end point is to add a subgroup to a group.

REST information

  • method: PUT
  • uri: {baseURI}/batches/{batchId}/groups/{groupId}/subgroups/{groupId}
  • query string arguments: none
  • request body: none

  • return code:

    • 200 Success if the subgroup was already part of the group
    • 201 Created if the subgroup was added to the group
    • 404 Not Found if either groupId or the batchId was not found
    • 5XX errors on errors
  • return content:

    • On success: no content
    • On error: see "standard errors"

Removing a subgroup from a group

Definition

The objective of this end point is to remove a subgroup from a group.

REST information

  • method: DELETE
  • uri: {baseURI}/batches/{batchId}/groups/{groupId}/subgroup/{groupId}
  • query string arguments: none
  • request body: none

  • return code:

    • 200 Success if the subgroup was removed from the group
    • 404 Not Found if either groupId or the batchId was not found
    • 5XX errors on errors
  • return content:

    • On success: no content
    • On error: see "standard errors"

 

 

Getting a group

Definition

This endpoint allows retrieving information about a group, specifically group properties.

REST information

  • method: GET
  • uri: {baseURI}/groups/{groupId}
  • query string arguments:
    • expandDepth - A number value specifying how deep users and groups are expanded. -1 means infinite recursion, 0 means do not specify users or groups, any other other number is the level of recursion while expanding.
  • request body: none

  • return code:

    • 200 Success if the group was found
    • 404 Not found if the groupId was not found
    • 5XX errors on errors
  • return HTTP header: none

  • return content:

    • On success: group resource
    • On error: see "standard errors"

 

Getting the user members of a group

Definition

This endpoint retrieves all users contained in a group

REST information

  • method: GET
  • uri: {baseURI}/groups/{groupId}/users
  • query string arguments: none
  • request body: none

  • return code:

    • 200 Success if the group was found
    • 404 Not found if the groupId was not found
    • 5XX errors on errors
  • return HTTP header: none
  • return content:
    • On success: group members resource with users list filled in
    • On error: see "standard errors"

Getting the subgroup members of a group

Definition

This endpoint retrieves all subgroups contained in a group

REST information

  • method: GET
  • uri: {baseURI}/groups/{groupId}/subgroups
  • query string arguments: none
  • request body: none

  • return code:

    • 200 Success if the group was found
    • 404 Not found if the groupId was not found
    • 5XX errors on errors
  • return HTTP header: none
  • return content:
    • On success: group members resource with subgroups list filled in
    • On error: see "standard errors"