Caplin Director v1 RESTful API

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

Contents:

User methods
Client methods
Permissioning messages
Other methods
Objects in the request and response body

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 a 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>

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 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

GET /clients

URL

/clients

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

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

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

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"}, …]`

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.

Valid values: true or false

Field specification object

A JSON encoded object describing a field.

Attribute Description Possible Values

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.

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.

Permission object

A JSON encoded object describing a permission.

Attribute Description

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.

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

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.

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

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.
`userDisabled`	`true` if the user is disabled. The user will not be sent to the Liberator.
`clientDisabled`	`true` if the client is disabled. The client and all its users will not be sent to the Liberator.
`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.

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.

userDisabled

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

clientDisabled

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

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

Attribute	Description
`clientKey`	The client’s id
`disabled`	If the client is disabled. The client and all its users will not be sent to the Liberator.
`version`	The version of this users 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
`priceTierKey`	The selected options keys for the clientFields "priceTierKey" fieldname

clientKey

The client’s id

disabled

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

version

The version of this users 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

priceTierKey

The selected options keys for the clientFields "priceTierKey" fieldname

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.