Sklik API Drak

API Usage

We use XML-RPC with a nil value extension. CET time zone is assumed in datetime fields. However we return timezone in datetime object too because of backward compatibility. Type 'binary' means XML-RPC base64 value (e.g. https://docs.python.org/2/library/xmlrpclib.html#binary-objects).

Authentication

You need to authenticate yourself before calling any XML-RPC method. See documentation of client.loginByToken() for information about user authentication. In every successive call of any method, you must pass given session string. First parameter is always struct with session string and optional id of managed user account:

struct user { string session int id (optional) }

You MUST pass managed user ID in order to manipulate entities you do not own directly.

Passing IDs and entities as parameters, diagnostics

Most functions now can process multiple entities at once. It's implemented by passing an array of ids or entity definitions. Method succeeds only if operation on all entities is finished correctly (or with minor warnings). Otherwise error status and diagnostics are returned and all changes are rolled back.

Method responses

Every method responds with a XML-RPC structure in this form:

{
    int status
    string statusMessage
    string session
    (additional data, depending on the actual XML-RPC method)
}
        

Status code 200 indicates that operation performed successfully. Other status codes indicate various kinds of warning or error states. Status code numbering is inspired by HTTP status codes:

• 200: Operation was successful
• 206: Operation was successful, but with warnings
• 4xx: Client side error (e.g. not found, access forbidden)
• 5xx: Server side error

How the XML-RPC response looks like for status code 200 (or 206) is documented in the given XML-RPC method documentation. Here is diagnostics example for status code 206 for ads.update(... creative1: "ahoj.." ...):

        
diagnostics = (
    [0] = {
        string field = "creative1"
        string id = "missing_space_after_dot"
        int objectId = 33216798
        int requestId = 0
        string type = "warning"
    },
    [1] = {
        string field = "creative1"
        string id = "consecutive_two_and_more_punctuation_chars"
        int objectId = 33216798
        int requestId = 0
        string type = "warning"
    }
)
        
        

Here you can see following information: field is entity attribute, where problem has been detected. id is just a string, that briefly describes problem. It will not be changed in the future. objectId is entity id, in this case ad id. requestId is an original index of the entity in array, as has been passed in method parameters. type is problem type. Here it is only warning, so update operation has been performed. If even one of the diagnostics has type set to error, then method will return 4xx code and nothing will be performed.

Status code 400 means that some parameters are missing, are in wrong type etc. In this case we try to help you figure out which parameters are missing or what is the problem. The XML-RPC method response has the following structure:

        
{
    int status = 400
    string statusMessage = "Bad arguments"
    array diagnostics = (
        [0] = {
            int actualParameters = 1
            string id = "wrong_parameters_count"
            int mandatoryParameters = 2
            int optionalParameters = 0
            string problemMessage = "Incorrect number of parameters"
        },
        ...
    )
}
        
        

Another example - missing attribute in ad definition:

        
{
    int status = 400
    string statusMessage = "Bad arguments"
    array diagnostics = (
        [0] = {
            field = "creative2"
            id = "missing_struct_field"
            problemMessage = "Field adsAttributes[0].creative2 must be present"
            structName = "adsAttributes[0]"
      }
    )
}
        
        

Status code 406 means that the data you provided is not acceptable because of our naming constraints, data duplication or value ranges. This usually means that the user of your software has entered invalid data, so in response we provide the error id and name of the field where the error occurred (if applicable) and possibly other information. Problem id is just a string, but we assume you might want to translate it so we try to make these error ids brief and we will not change them in future (in the current Sklik API major version). The 406 error response looks like this:

        
{
    int status = 406
    string statusMessage = "Bad values of attributes Some element(s) has(have) bad values of attributes!"
    array diagnostics (
        [0] = {
            string id = "exclamation_mark",
            string field = "creative1",
            int requestId = 0,
            string type = "error"
        },
        [1] = {
            string id = "missing_space_after_dot",
            string field = "creative1",
            int requestId = 1,
            string type = "warning"
        },
        ...
    )
}
        
        

Note that there are XML-RPC methods that do only data validation (their name ends with check). They cost less than the data-changing methods, so it is advantageous to use them.