Desktop Interface API Client Requests

Cisco Finesse Release 12.5(1) or higher supports only secure HTTP (HTTPS) requests from clients. Cisco Finesse desktop operations can be performed using the available REST HTTPS request described in this guide.

Operations on specific objects are performed using the ID of the object in the REST URL. For example, the URL to view a single object (HTTPS) would be:

Copy
https://<FQDN>:<port>/desktop/api/<object>/<objectID>
 

FQDN is the fully-qualified domain name of the Finesse server.

Finesse APIs use the following HTTP methods to make requests:

• GET: Retrieve a single object or list of objects (for example, a single user or list of users).

• PUT: Replace a value in an object (for example, to change the state of a user from NOT_READY to READY).

• POST: Create a new entry in a collection (for example, to create a new reason code or wrap-up reason).

• DELETE: Remove an entry from a collection (for example, to delete a reason code or wrap-up reason).

Finesse uses the standard HTTP status codes (for example, 200, 400, and 500) in the response. These status codes indicate overall success or failure of the request.

If an API operation fails, a detailed error is returned in the HTTP response message body. The error, in JSON format, appears as follows:

Copy
{
   status : 400, apiErrors :
   {
      "errorType": "Bad Request",
      "errorMessage": "Security Exception",
      "errorData": "Error in getting desktop configs."
   }
}
 

Finesse has a Dependency Manager that collects the state of internal dependencies for Finesse (such as the state of the Cisco Finesse Notification Service) and reports these states to external entities.

If any of these dependencies are down, Finesse is out of service. If the Cisco Tomcat is running, Finesse rejects any API requests and returns an HTTP 503 error. The error appears as follows:

Copy
{
   status : 400, apiErrors :
   {
      "errorType": "Bad Request",
      "errorMessage": "Security Exception",
      "errorData": "Error in getting desktop configs."
   }
}
 

If the Cisco Finesse Tomcat service is not running, Finesse returns a Connection Timeout error.