Last updated: Dec 15, 2019 12:14

Get started with the Perfecto REST APIs, a RESTful web service that provides an interface for accessing CQ Lab functionality and data from a remote client over the web.

API Operations

The following API operations are available:

Operation	Description
Command	Run a sequence of Perfecto automation commands
Script	Start script executions, get status, aborting and listing
Report	Download reports, images, video, vitals & network information
Repository	Upload & Download items, list, delete and clean the repository
Device, Device Host & Cradle	Get info on one or all devices, device hosts, or cradles
Scheduler	Create, update, delete and list scheduled scripts
User & Account	Create, update, list and delete users
Group	Create, update, list and delete groups
Reservation	Reserve devices

URL Structure

The following is the API URL request structure:

https://<hostName>/services/<resourceGroup>/<resourceIdentifier>?operation=<value>&<mandatoryParameter>=<value>&<optionalParameter>=<value>

<hostName>: Host name for the service. For example, mycloud.perfectomobile.com.
<resourceGroup>: a resource group. For example, executions.
<resourceIdentifier>: A resource identifier. This is only required if the API call is on a specific resource such as aborting a specific execution.
operation: The operation to perform. For example, abort.
<mandatoryParameters>: One or more required parameters specified using name-value pairs prefixed by the & character. For example, &offlineToken=securityToken.
<optional parameters>: One or more optional parameters specified using name-value pairs prefixed by the & character. For example, &responseFormat=XML.

Authentication & Authorization

It is required to send some form of authentication:

If your Perfecto Lab supports the security token, it is strongly recommended to use the securityToken parameter to provide your personal valid token.

https://mycloud.perfectomobile.com/services/handsets?operation=list&securityToken=mySecurityToken&status=connected

Deprecated. For OnPrem and Perfecto Labs that do not support the token, the user and password for authentication should be supplied in each request.
Note: Going forward, all authentication requires a security token. For information on obtaining a security token, see Generate security tokens.

https://mycloud.perfectomobile.com/services/handsets?operation=list&user=myUsername&password=mypassword&status=connected

Some operations require specific user permissions. For example user operations requires administrator or user management role.

Protocols

The API request can be transmitted to the API server using either the GET or the POST HTTP methods. To use the GET method, simply specify the request as a URL. Parameter values must be encoded to prevent conflicts with HTTP special characters. The following example shows the URL for getting a list of all connected handsets in mycloud.

https://mycloud.perfectomobile.com/services/handsets?operation=list&securityToken=<your_token>&status=connected

You can get the same list using the POST method specifying the POST parameters as follows:

URL: https://mycloud.perfectomobile.com/services/handsets
Request: operation=list&securityToken=<your_token>&status=connected

Operations that upload files to the Perfecto repository must use POST or PUT method.

Response Formats

The default response format is JSON. Most operations support the optional parameter responseFormat for specifying the required format. A few operations support only XML response format.

JSON - For more information about the JSON format, see http://www.json.org.
XML - the response is an XML document.

The following examples show the response type for a request to start a new execution:

JSON

{
    "executionId" : "samb@perfectomobile.com_controller_16-11-03_08_32_32_4",
    "testGridReportUrl" : "https://mobileCloud.reporting-01.perfectomobile.com?externalId[0]=samb@perfectomobile.com_controller_16-11-03_08_32_32_4",
    "singleTestReportUrl" : "https://mobilecloud.perfectomobile.com/nexperience/singletest/report/?reportRepositoryKey=PRIVATE:controller/161103/controller_16-11-03_08_32_32_4.xml&ownerId=samb@perfectomobile.com&sharingCode=700d8374-776c-4147-8ae4-9cc1b11980ca",
    "reportKey" : "PRIVATE:controller/161103/controller_16-11-03_08_32_32_4.xml"
}

XML

<response>
    <executionId>
        samb@perfectomobile.com_controller_16-11-03_08_39_41_5
    </executionId>
    <testGridReportUrl>
        https://mobilecloud.reporting-01.perfectomobile.com?externalId[0]=samb@perfectomobile.com_controller_16-11-03_08_39_41_5
    </testGridReportUrl>
    <singleTestReportUrl>
        https://mobilecloud.perfectomobile.com/nexperience/singletest/report/?reportRepositoryKey=PRIVATE:controller/161103/controller_16-11-03_08_39_41_5.xml&ownerId=samb@perfectomobile.com&sharingCode=9aeaf95e-599f-4234-92b5-31e4627b765d
    </singleTestReportUrl>
    <reportKey>
        PRIVATE:controller/161103/controller_16-11-03_08_39_41_5.xml
    </reportKey>
</response>

Test Your API Access

Open a web browser.
Type: https://yourCloud.perfectomobile.com/services/handsets?operation=list&securityToken=<your_token>
in the address bar, substituting myCloud, myUsename, and myPassword as appropriate, and then type ENTER.
Confirm that an XML list of devices is returned by the API.

Error Handling

Error messages returned in the response of an API operation are self-explanatory and should be sufficient to resolve issues, as can be seen from the following examples:

# Cause: The specified execution id could not be found
# Resolution: Verify that the executionId is correct
{"errorMessage":"Failed to get execution status - Execution executionId wasn't found"}
# Cause: The specified user does not have sufficient permission to perform the requested operation
# Resolution: If you want to use this operation, you can either use a user with the correct permissions or request the correct permission for this user
{"errorMessage":"Failed to get execution list - User username is not authorized to get all script executions"}
# Cause: The specified parameter is not valid for the abort operation
# Resolution: If the parameter is valid for this operation then report the issue, otherwise remove the parameter and try again
{"errorMessage":"Failed to abort script - Request contains unknown parameters: [time.offset]"}

The following table provides guidance for resolving some of the common HTTP codes that you may encounter:

Response	Cause	Resolution
400 Bad Request	One or more of the specified parameters is not valid.	Fix incorrect parameters in the URL.
401 Unauthorized	Authentication is required and has failed.	Fix incorrect user/password parameters in the URL.
500 Internal server error	Internal server error.	Contact your system administrator.

Common Errors For Invalid HTTP API URLs

JSON Response

# Cause: Invoking the HTTP API without using HTTPS
# Resolution: Use HTTPS
{"errorMessage":"The operation requires secured channel"}
# Cause: Invoking the HTTP API with an unknown resource
# Resolution: Verify that the resource name is correct
{"errorMessage": "Could not find resource 'startexecutions'"}
# Cause: Invoking the HTTP API with an unknown operation
# Resolution: Verify that the operation name is correct
{"errorMessage": "Could not find operation 'executescript' for resource 'executions'"}

XML Response

<!--Cause: Invoking the HTTP API with an unknown operation-->
<!--Resolution: Verify that the operation name is correct-->
<response>
	<errorMessage>Could not find operation 'executescript' for resource 'executions'</errorMessage>
</response>

Page tree

REST API