Caplin Director v2 RESTful API

This page provides a description of the methods in the Caplin Director v2 RESTful API.

User methods

The following methods are available for managing users.

Create a user

POST /user

URL

/user

Method

POST

Success code

201 Created

Failure code

500 Server error

400 Bad request

Request body

User object

Response body

User object or Error object

Request headers

Response headers

URL of user returned in the HTTP Location header

Back to Contents

Get user

GET /user/<userKey>

URL

/user/<userKey>

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

User object or Error object

Request headers

Response headers

Back to Contents

Get all users for a client

GET /users?clientKey=<clientKey>

See also Get a client’s directory of clients and users.

URL

/users?clientKey=<clientKey>

Method

GET

Success code

200 OK

Failure code

500 Server error

400 Bad request

Request body

Response Body

Array of User objects or Error object

Request headers

Response headers

Back to Contents

Update a user

PUT /user

URL

/user

Method

PUT

Success code

200 OK

Failure code

500 Server error

400 Bad request

Request body

User object

Response body

User object or Error object

Request headers

Response headers

Back to Contents

Validate a user

POST /validate/user

URL

/validate/user

Method

POST

Success code

200 OK

Failure code

500 Server error

400 Bad request

Request body

User object

Response body

Error object (on failure)

Request headers

Response headers

Back to Contents

Delete a user

DELETE /user/<userKey>

URL

/user/<userKey>

Method

DELETE

Success code

204 No Content

Failure code

500 Server error

Request body

Response body

Error object (on failure)

Request headers

Reponse headers

Back to Contents

Client methods

The following methods are available for managing clients.

Create a client

POST /client

URL

/client

Method

POST

Success code

201 Created

Failure code

500 Server error

400 Bad request

Request body

Client

Response body

Client object or Error object

Request headers

Response headers

URL of client returned in the HTTP Location header

Back to Contents

Get a client

GET /client/<clientKey>

URL

/client/<clientKey>

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

Client object or Error object

Request headers

Response headers

Back to Contents

Get all clients

This Director v1 method has been replaced by Get a client’s child clients and users.

Back to Contents

Get a client’s directory of clients and users

GET /client/<clientKey>/directory

This method replaces the Director v1 GET /clients method.

URL

/client/<clientKey>/directory

Method

GET

Success code

200 OK

Failure code

500 Server error

400 Bad request (if <clientKey> is null)

Request body

Response body

If <clientKey> is less than or equal to 0, then this method returns an array of Client objects for all clients in Director.

If <clientKey> is greater than 0, then this method returns an array of child Client objects and child User objects.

Request headers

Response headers

 
GET /search/<requestId>/<searchTerm>

URL

/search/<requestId>/<searchTerm>

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

Array of Client objects or Error object

Request headers

Response headers

Back to Contents

Update a client

PUT /client

URL

/client

Method

PUT

Success code

200 OK

Failure code

500 Server error

400 Bad request

Request body

Client object

Response body

Client object or Error object

Request headers

Response headers

Back to Contents

Move a client

GET /client/<clientKey>/move/<parentClientKey>

URL

/client/<clientKey>/move/<parentClientKey>

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

Error object on failure

Request headers

Response headers

Back to Contents

Validate a client

POST /validate/client

URL

/validate/client

Method

POST

Success code

200 OK

Failure code

500 Server error

400 Bad request

Request body

Client object

Response body

Error object (on failure)

Request headers

Response headers

Back to Contents

Validate a client move

GET /validate/client/<clientKey>/move/<parentClientKey>

URL

/validate/client/<clientKey>/move/<parentClientKey>

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

Client-move validation result object

Request headers

Response headers

Back to Contents

Delete a client

DELETE /client/<clientKey>

URL

/client/<clientKey>

Method

DELETE

Success code

204 No Content

Failure code

500 Server error

Request body

Response body

Request headers

Response headers

Back to Contents

Permissioning messages

The following methods are available for managing permissions.

Get all enabled client-permissions

GET /client/<clientKey>/enabled

URL

/client/<clientKey>/enabled

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

Array of permission keys or Error object

Request headers

Response headers

Back to Contents

Add an enabled client-permission

POST /client/<clientKey>/enabled/<permissionKey>

URL

/client/<clientKey>/enabled/<permissionKey>

Method

POST

Success code

201 Created

Failure code

500 Server error

Request body

Response body

Request headers

Response headers

Empty URL

Back to Contents

Remove an enabled client-permission

DELETE /client/<clientKey>/enabled/<permissionKey>

URL

/client/<clientKey>/enabled/<permissionKey>

Method

DELETE

Success code

204 No content

Failure code

500 Server error

Request body

Response body

Request headers

Response headers

Back to Contents

Get all disabled user-permissions

GET /user/<userKey>/disabled

URL

/user/<userKey>/disabled

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

Array of permission keys or Error object

Request headers

Response headers

Back to Contents

Add a disabled user-permission

POST /user/<userKey>/disabled/<permissionKey>

URL

/user/<userKey>/disabled/<permissionKey>

Method

POST

Success code

201 Created

Failure code

500 Server error

Request body

Response body

Request headers

Response headers

Empty URL

Back to Contents

Remove a disabled user-permission

DELETE /user/<userKey>/disabled/<permissionKey>

URL

/user/<userKey>/disabled/<permissionKey>

Method

DELETE

Success code

204 No content

Failure code

500 Server error

Request body

Response body

Request headers

Response headers

Back to Contents

Create an account

POST /account

URL

/account

Method

POST

Success code

201 Created

Failure code

500 Server error

Request body

Permission object

Response body

Permission object or Error object

Request headers

Response headers

Empty URL

Back to Contents

Update an account

PUT /account

URL

/account

Method

PUT

Success code

201 Created

Failure code

500 Server error

Request body

Permission object

Response body

Permission object or Error object

Request headers

Response headers

Empty URL

Back to Contents

Delete an account

DELETE /client/<clientKey>/account/<permissionKey>

URL

/client/<clientKey>/account/<permissionKey>

Method

DELETE

Success code

204 No content

Failure code

500 Server error

Request body

Response body

Request headers

Response headers

Back to Contents

Get all accounts for client

GET /client/<clientKey>/accounts

URL

/client/<clientKey>/accounts

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

Array of Permission objects or Error object

Request headers

Response headers

Back to Contents

Other methods

The following miscellaneous methods are also available.

Client and user field meta-data and permissions

GET /configuration

URL

/configuration

Method

GET

Success code

200 OK

Failure code

500 Server error

Request body

Response body

Configuration object

Request headers

Response headers

Back to Contents

Ping (noop)

POST /system/ping

URL

/system/ping

Method

POST

Success code

200 OK

Failure code

Request body

Response body

Request headers

Response headers

Back to Contents

Logout

GET /logout

URL

/logout

Method

GET

Success code

302 OK

Failure code

500 Server error

Request body

Response body

Request headers

Response headers

Redirection (Location header) to root context

Back to Contents

Objects in the request and response body

All objects in the request and response body are JSON encoded.

Error object

A JSON encoded object describing an error.

Attribute Description

error

Error status.

Possible values:

  • "Failure": Server error

  • "Stale": The data has already been modified by another user

  • "Invalid": The supplied data is invalid for the reasons supplied in the supplemental errorDetail or validationErrors attributes.

errorDetail

[optional] Error text

validationErrors

[optional] Validation errors in the form [{"fieldName":"text", "fieldError", "text"} , {"fieldName":"text", "fieldError", "text"}, …​]

Configuration object

A JSON encoded object that contains data needed to use the rest API with the other JSON objects.

Attribute Description

clientFields

An array of field specification objects

userFields

An array of field specification objects

accountFields

An array of field specification objects

permissions

Array of permission objects

permissionGroups

Array of group objects

sessionUser

The user name of the administrator logged into Director

meta

For use by Director’s GUI.

An object with the following attributes:

Attribute Description

hasPriceTier

Indicates whether the Director database includes price tier data.

Valid values: true or false

allowEditAccount

Indicates whether the account editing widget is enabled. See configuration item allow-edit-account.

Valid values: true or false

allowClientDirectoryDeletion

Indicates whether Director allows the deletion of clients containing users and/or child clients. See configuration item allow-not-empty-client-deletion.

Valid values: true or false

isReadOnly

Indicates whether the user of the REST API has read-only access to Director. A user has read only access if they do not have at least one entry in the Roles table with the value 'CRUD' in the ROLEACTION column.

Valid values: true or false

denyRootLevelClientCreation

Indicates whether Director permits the creation of root-level clients. See configuration item deny-root-level-client-creation.

Valid values: true or false

isHierarchical

Indicates whether clients are displayed in a hierarchy in Director. See configuration item allow-client-hierarchy.

Valid values: true or false

Field specification object

A JSON encoded object describing a field.

Attribute Description Possible Values

fieldName

The name of the attribute the spec is for

-

displayName

A user readable name

-

displayType

How to display the attribute

For account fields, the only valid value is: account-text.

For client and user fields, the value can be one of: select, checkbox, or text

fieldType

The attributes data type

One of string, integer, decimal, or boolean

optional

true if the field is required

true or false

editMode

How the client can modify the attribute

One of read, write, or write-once

validations

Array of validations

Validations have attributes rule and errorMessage, where rule is one of: NotEmpty, MinLength=<int>,

MaxLength=<int>, or RegEx=<regular expression>

options

Array of options

Only has options if displayType is selected. Option has attributes key (an index) and value (text).

defaultValue

The default value for the attribute

Null if there is no default value.

Client-move validation result

A JSON encoded object describing the validation result.

Attribute Description Possible Values

resultCode

The verification result

One of three values:

  • "OK"

  • "ACCEPTANCE_REQUIRED"

  • "ERROR"

resultReason

Detailed description of validation failure

One of six values:

  • "Cannot have a client key or parent key of null or -1"

  • "Unable to move group within itself"

  • "Unable to locate the parent group"

  • "Attempted to move to same position in the hierarchy"

  • "A group cannot be moved to a position beneath itself"

  • "A group cannot be moved to a disabled parent"

permissionsToBecomeDenied

Permissions that will be revoked as a result of the move.

A map, keyed by client, of arrays of Permission objects. The map’s keys are client objects serialised to strings.

Example map:

"permissionsToBecomeDenied": {
  "ClientEntity{clientKey=1001, …}": [
    {
      "permissionKey":23,
      "description":"Benchmark",
      "action":"BENCHMARK",
      "tags":{},
      "customFields":{},
      "groupKey":3,
      "permissionOrder":14,
      "type":"boolean"
    },
    â‹®
  ],
  â‹®
}

requestedClient

The client to be moved.

Client object.

Permission object

A JSON encoded object describing a permission.

Attribute Description

permissionKey

Used to identify this permission in other rest requests.

description

A user readable name.

type

How the permission is to be displayed

action

The permissions action, as used by the permissioning API.

tags

JSON object of custom attributes / values as configured in Director’s database.

groupKey

ID of the group this permission belongs to.

permissionOrder

Integer. Used when ordering a list of permissions in the Director GUI. Permissions with a lower permissionOrder value are displayed higher in the list than permissions with a higher permissionOrder value.

Group object

A JSON encoded object describing a group.

Attribute Description

groupKey

The group’s ID.

groupName

Displayed title of the group.

groupOrder

Used to order the display of the group.

permissionType

How the group is to be displayed.

User object

A JSON encoded object describing a user.

Attribute Description

userKey

The user’s id.

clientKey

The id of the client the user belongs to.

username

The user’s Liberator login name.

firstName

The user’s first name.

lastName

The user’s last name.

disabled

true if the user is disabled. The user will not be sent to the Liberator.

This attribute replaces the Director v1 REST API attribute userDisabled.

disabledInHierarchy

true if an ancestor client is disabled. The client and all its users will not be sent to the Liberator.

This attribute replaces the Director v1 REST API attribute clientDisabled.

version

The version of this user’s data. When client receives a version of 1 it must send a version of 1 on updates. If the current version does not match, the update will fail.

Custom user fields defined in the Director database appear as extra attributes on the User object. If a custom user 'address' field is defined in the database, for example, it would be be included as an 'address' attribute of the User object. For information on how to create custom fields, see Defining custom fields.

Client object

A JSON encoded object describing a client.

Attribute Description

clientKey

The client’s id

parentClientKey

The key of the client’s parent, or 0 if the client is a root-level client.

disabled

True if the client is disabled. The client and all its users will not be sent to the Liberator.

disabledInHierarchy

True if an ancestor of the client is disabled.

version

The version of this user’s data. When client receives a version of 1 it must send a version of 1 on updates. If the current version does not match the update will fail.

clientName

Client short name

displayName

Client display name

fields

Map of custom field names and values. Example: fields: {"fieldname":"fieldvalue", …​}

priceTierKey

The ID of a pricing tier

fwdPriceTierKey

[Optional] The ID of a pricing tier

Custom client fields defined in the Director database appear as extra attributes on the Client object. If a custom client 'address' field is defined in the database, for example, it would be be included as an 'address' attribute of the User object. For information on how to create custom fields, see Defining custom fields.