Caplin Director v2 RESTful API

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

Contents:

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  

Search for clients

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: NotEmptyMinLength=<int>,
MaxLength=<int>, or RegEx=<regular expression>

options Array of options Only has options if displayType is select. 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.

Note: 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.

Note: 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.