Caplin Director v1 RESTful API

This page provides a description of the methods in the Caplin Director v1 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 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
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
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.

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