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

• Create a group

• Delete a group

• Get a group

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:

Optional Properties:

Group member resource

Example:

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

Optional Properties:

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"