API overview

Help
/
API myTarget
/
API overview

API overview

Authentication
Basic data types
Basic errors
Response compression
Limits for the number of requests per time unit
Testing

API standards

API is implemented as a set of "resources" (domain models) and "methods" (operations with resources) which is somewhat similar to the REST API design. The core difference is that in MyTarget API, many methods can operate with complex resources that may include other resources with various numbers of nesting levels and/or lists of other resources. Many methods also support operations with several resources of the same type.

Every resource has one or more types of URL addresses. Operations with resources are performed by various HTTP methods. For example, the following request retrieves a list of campaigns:


GET /api/v2/campaigns.json

The following request creates a campaign:


POST /api/v2/campaigns.json

The following request retrieves parameters of a certain campaign:


GET /api/v2/campaigns/1.json

Most methods use the JSON format for both input and output data. Consequently, the HTTP requests and responses are of the application/json type. For the GET and DELETE requests that do not have a request body, specifying the type is optional.

Validation of the input data and generation of the output for each resource is performed according to one or more "data structures". Every method description specifies the structures used by the method.

Authentication

Authentication and authorization in the API is done with the OAuth2 protocol. Its implementation is described in this article. To access the API via OAuth2, you need to submit a corresponding request (from the support contact form in the interface or ads_api@vk.team). To get access to the API, follow these instructions.

Basic data types

API uses the following basic data types:

Complex data types based on the above types are described in the methods and resources documentation.

Basic errors

Error messages have standard HTTP response statuses. The response body contains detailed information about error in the JSON format; the response type is application/json.

400 — the request contains invalid data
401 — the signature used for authentication is invalid or missing (the Authorization heading must contain a valid access_token value)
403 — the operation cannot be performed under the account whose secret key (access_token) was used to sign the request
404 — the requested resource cannot be found
405 — the resource does not support the current HTTP method
413 — the request body is too long
429 — the requests-per-time unit limit was exceeded
500 — unexpected error

Response compression

If your client supports response compression, you can use the following heading in the request:


Accept-Encoding: gzip, deflate

Limits for the number of requests per time unit

The service has limitations for the number of requests user can send during a time interval (calendar day, hour, second).

User limits are calculated for each user individually. For example, if the system has a limit of 10 requests per minute for a particular method, it means that each user can make up to 10 requests in a minute.

Limits may be adjusted for each user or user group. That is why it is recommended to analyse only real-time data.

Current limits are returned in the HTTP headings of every response. Note that values may differ from method to method.


X-RateLimit-RPS-Limit: value     # number of requests per second 
X-RateLimit-Hourly-Limit: value  # number of requests per hour 
X-RateLimit-Daily-Limit: value   # number of requests per day

The responses also contain headings with the number of requests user can send before exceeding the threshold:


X-RateLimit-RPS-Remaining: value    # number of requests user can make within the current second 
X-RateLimit-Hourly-Remaining: value # number of requests user can make within the current hour 
X-RateLimit-Daily-Remaining: value  # number of requests user can make within the current day

You can also get information about the limits for a specific user by request:


GET /api/v2/throttling.json

The response contains the current value of the limits, as well as the number of remaining requests for resources for which the limits are set.


{
    "REMARKETINGUSERSLIST": {
        "v2": {
            "READ": {
                "remaining": {
                    "60": 1
                },
                "limits": {
                    "60": 1
                }
            },
            "CREATE": {
                "remaining": {
                    "60": 0
                },
                "limits": {
                    "60": 0
                }
            }
        },
        "v3": {
            "READ": {
                "remaining": {
                    "3600": 200
                },
                "limits": {
                    "3600": 200
                }
            },
            "CREATE": {
                "remaining": {
                    "3600": 10
                },
                "limits": {
                    "3600": 10
                }
            }
        },
        "all": {
            "READ": {
                "remaining": {
                    "3600": 200
                },
                "limits": {
                    "3600": 200
                }
            },
            "CREATE": {
                "remaining": {
                    "60": 1
                },
                "limits": {
                    "60": 1
                }
            }
        }
    }

For a resource, both general limits and limits for using the method of a specific version can be set. The version corresponds to the namespace.

So, in the above example, using the /api/v2/remarketing/users_lists/<id>.json method, you can make no more than one GET request per minute, and you cannot create a new list, using /api/v2/remarketing/users_lists/<id>.json you can read the information on 200 lists per hour, and create 10 lists per hour. And at the same time, using requests of any versions, in total, it is impossible to read the information on more than 200 lists per hour, and you can create no more than 1 list per hour.

After a new version of the method release, we will gradually reduce the usage limits for previous versions of the same resource.

Testing

There is a stand-alone service instance that is used as a testing environment for testing and debugging the API integration: https://target-sandbox.my.com. To use it, you will need another ID and secret key (not the ones used for accessing the production environment). Follow these instructions to get access to the environment.

API standards

The following rules apply to all methods.

Request parameters

Name

Format

Default

Description

fields

<field_name>[,<field_name>]*

Depends on resource

List of fields for the top-level object.

fields=id,name

limit

integer

20

The number of objects in the search results. Maximum 50.

limit=10

offset

integer

0

Offset by objects in the search results.

sorting

[-]?<field_name>[,[-]?<field_name>]*

-

Sorting by object fields. The list of sorted fields is unique for each resource. <field_name> - ASC -<field_name> - DESC

sorting=id,-created

_<field_name>__<field_lookup>

<value>[,<value>]*

-

Filters by object fields.

The list of filtered fields is unique for each resource.

You cannot filter by the fields of nested objects.

_id__in=1,2,3 _status__ne=active _updated__gt=2018-01-01 00:00:00

_<field_name>

<value>

-

Filter for equality by object field. The rules are the same as in _<field_name>__<field_lookup>

_id=1

offset=500

Field lookups

ne - not equal
lt - less than
lte - less or equal
gt - more than
gte - more or equal

Response

Collection


{
    "count": int,  // total number of objects, after applying all other parameters
    "offset": int, // current offset
    "limit": int, // number of objects in search results
    "items": [{
        "<field_name>": field_value,
        ...
    }, ...]
}

Object


{
    "<field_name>": field_value,
    ...
}

Was this article helpful?