Understanding how to call our APIs

Learn about the technical concepts related to calling our APIs and understanding their responses

Authorization

All requests to our APIs must be authorized. Anonymous requests are denied in all cases. Authorization involves the use of an access token. For detailed information, see Authenticating your data source to use our APIs.

Requests

Affective Computing (powered by Virtue)'s infrastructure is powered by web REST APIs. Data resources are accessible to an API endpoint via standard HTTPS requests in UTF-8 format.

Our APIs use HTTP/2 as their underlying protocol. When making API requests, do not try to enforce the HTTP/1 or HTTP/1.1 protocol, as it will result in an HTTP 464 error.

Responses

This section describes the formats of responses and errors received from our APIs.

Our web REST APIs use standard HTTP response status codes, as defined in RFC 2616 and RFC 6585.

Response format

Web REST API responses typically include a JSON object.

The unified response format for all endpoints of our APIs is as follows:

{    
    "result": {},
    "targetUrl": null,
    "success": true,
    "error": null,
    "unAuthorizedRequest": false
}

For successful calls to our APIs, you'll receive an HTTP response status code 200 response. The response will include a JSON object or list depending on the requested endpoint.

The following example illustrates a successful response:

{
    "result": {
        "interaction_identifier": "1379296_15",
        "last_stage": false,
        "repeat_stage": false,
        "change_mode": null,
        "next_participant": null,
        "status": "success",
        "errorcode": "",
        "errorMessage": "",
        "actions": [
            {
                "interaction_channel_id": 27085,
                "action_type": "Statement",
                "executable": "Hi, how are you?  hello, how are you doing?"               
            }
        ]
    },
    "targetUrl": null,
    "success": true,
    "error": null,
    "unAuthorizedRequest": false,
    "__abp": true
}

Error responses

Web REST APIs use the following formats to describe an error:

Error type	HTTP status code	Example
Validation Error Object	400	{ "result": null, "targetUrl": null, "success": false, "error": { "code": "ER000n", //Error code "message": "The Error Message", "details": "REF_nnnnnnnn", //Unique reference to this error that you can use for support. "validationErrors": null }, "unAuthorizedRequest": false, "__abp": true }
Too Many Requests	429	{ "result": null, "targetUrl": null, "success": false, "error": { "code": "INF001", "message": "You have exceeded the allowed hit rate limit per minute", "details": "", "validationErrors": null }, "unAuthorizedRequest": false, "__abp": true }
Incompatible Protocol	464
Regular Error Object	500	{ "result": null, "targetUrl": null, "success": false, "error": { "code": "EX000n", //Error code "message": "The Error Message", "details": "REF_nnnnnnnn", //Unique reference to this error that you can use for support. "validationErrors": null }, "unAuthorizedRequest": true, "__abp": true }

The following example illustrates an error response when a validation error occurs:

{
    "result": null,
    "targetUrl": null,
    "success": false,
    "error": {
        "code": "ER0001", //Error code
        "message": "Insufficient participants.\nPlease add at least 2 participants with unique and active interaction sessions.",
        "details": "REF_8FF9E635", //Unique reference to this error that you can use for support.
        "validationErrors": null
    },
    "unAuthorizedRequest": false,
    "__abp": true
}

For detailed information about the different error codes that could occur when working with our APIs, see Error messages.

Pagination and filtration

For endpoints that return large amounts of data, you can retrieve data sets in a structured manner. You can use the following pagination and filtration parameters in your API query:

Parameter	Description
SkipCount	A pagination parameter that helps you define the number of results to skip (i.e. where to start counting) when returning results.
MaxResultCount	A pagination parameter that helps you limit the number of results returned. It specifies the number of returned results.
Keyword	A filtration parameter that helps you filter the returned results by a specific keyword.

For example, if you have already retrieved 50 results and want to view the next 10 results, you can pass 50 to SkipCount and 10 to MaxResultCount.

The following example illustrates how to use these parameters:

$ curl https://api.virtuedeep.tech/api/services/app/FeedingData/GetAll?Keyword=Project_1&SkipCount=20&MaxResultCount=5

The request in this example retrieves the next 5 results (based on the limit set in MaxResultCount) after the 20th result (based on the offset value configured in SkipCount) and filters the results by the term Project_1 (based on the filter set in Keyword).