This section describes how input and output are handled for all methods, and what generic parameters are available to modify this behavior. All input data must be encoded as valid JSON, and all responses will similarly be returned as JSON. Both GET and POST HTTP methods are supported for all API methods, and the response will be identical regardless of the HTTP method used. For details about the JSON input and output for each API method, see their respective documentation.
All API requests reference the endpoint https://api.cxense.com and, unless otherwise noted, require authentication. In the following, the utility cx.py is used to set the correct authentication headers.
POST requests
For POST requests, the JSON input data is provided as part of the message body.
$ cx.py /profile/content/fetch '{"url":"http://www.example.com"}'
{
"url": "http://www.example.com",
"id": "0caaf24ab1a0c33440c06afe99df986365b0781f"
}
GET requests
For GET requests, the JSON input data must be URL encoded and provided in the json parameter. In addition GET requests has support for JSONP and response wrapping as described below.
You have to use operating system specific parameter escaping (double or single quotes) for Bash and Windows Shell, because the ampersand '&' character is a reserved in each environment.
$ cx.py '/profile/content/fetch?json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D'
{
"url": "http://www.example.com",
"id": "0caaf24ab1a0c33440c06afe99df986365b0781f"
}
Response wrapping
By providing the parameter wrap_response with value true the response will be wrapped in a JSON object containing the keys httpStatus and response. The HTTP status code for the request will always be 200, even if the request fails. The httpStatus field will contain the actual status code, while response will contain the response object.
$ cx.py '/profile/content/fetch?wrap_response=true&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D'
{
"httpStatus": 200,
"response": {
"url": "<a href="http://www.example.com/">http://www.example.com"</a>,
"id": "0caaf24ab1a0c33440c06afe99df986365b0781f"
}
}
JSONP with callbacks
By providing the parameter callback with a value specifying a callback method, the response will change to use JSONP. Specifically, the HTTP header Content-Type will be set to text/javascript, and the content will be a JavaScript method call using the specified value for callback value as the method name, and the response as the first and only parameter. The callback method can only contain ASCII characters, digits and underscores.
Specifying a callback method also changes the default value of wrap_response to true. Response wrapping can be turned off explicitly.
Example GET request with JSONP callback and response wrapping
$ cx.py '/profile/content/fetch?callback=callback_method&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D'
/**/
callback_method({"httpStatus":200,"response":{"url":"http://www.example.com","id":"0caaf24ab1a0c33440c06afe99df986365b0781f"}})
Example GET request with JSONP callback and no response wrapping
$ cx.py '/profile/content/fetch?callback=callback_method&wrap_response=false&json=%7B%22url%22%3A%22http%3A%2F%2Fwww.example.com%22%7D'
/**/
callback_method({"url":"http://www.example.com","id":"0caaf24ab1a0c33440c06afe99df986365b0781f"})
Use of callback and response wrapping are unsupported for /traffic/data, /dmp/traffic/data.
Batch requests
For most APIs it is possible to send in multiple request objects in a single HTTP request. This is performed by using an array of request objects. It is only possible to perform requests against a single API path. If successful the response will be an array with the same number of response objects in the corresponding order as the request objects.
If one or more of the request objects fails, an error result will be returned for the objects that fail. The returned HTTP status code will be the highest status code that would have been returned for each request object.
If the entire request fails, the response will be a single object with error details. This can for instance happen if invalid JSON is provided, the request times out or too many request objects are provided. It is recommended to keep the number of request objects fairly low to avoid timeouts causing failures for an entire batch. The maximum number of request objects is currently 100 per batch request.
Batch request example
$ cx.py /profile/content/fetch '[{"url":"http://www.example.com"},{"url":"http://www.example.com/foo"},{"url":"invalid"}]'
[
{
"url": "http://www.example.com",
"id": "0caaf24ab1a0c33440c06afe99df986365b0781f",
},
{
"url": "http://www.example.com/foo",
"id": "4d5f046cfef9abccc5f77e403352712a7fd88536",
},
{
"error": "Invalid request: Invalid URL"
}
]