Change log
| Date | API version | Change |
|---|---|---|
| 4 September 2015 | v1.33 | Added authentication reference |
| 24 September 2015 | v1.35 | Add "last-modified" support |
| 10 October 2015 | v1.36 | Added object "forecast" for advertiser |
| 5 November 2015 | v1.37 | Campaigns, campaign_groups, creatives, sites added to common objects |
Introduction
This document describes the API of GetIntent RTBSuite platform. The API consists of three major services:
- Common API service: allows to create and edit common RTB entities
- Advertiser API service: allows to manage advertiser related entities (creatives, segments and etc)
- Reporting API service: allows to get available reporting information campaign performance, available inventory, etc.
General approach
API is built as JSON RESTful service and support standard GET/PUT/DELETE methods over HTTP 1.1 protocol.
| GET | read/retrieve |
| PUT | create/add/update/modify |
| DELETE | delete |
API endpoint
API endpoint is RTBSuite UI hostname, general API URL pattern is:
| Блок кода | ||
|---|---|---|
| ||
http://<ui.getintent.com>/api/v1/<object_type>/<action>(/<id>)?token=<token> |
<ui.getintent.com> should be replaced by proper RTBSuite UI domain. <token> is authentication token (can be obtained through user settings in RTBSuite UI).
JSON data model
RTB data model contains several entities, each entity has it’s own JSON representation with name and id:
| Блок кода | ||
|---|---|---|
| ||
{
id: 1,
name: "<name>",
...
} |
Also some objects may belong to a specific advertiser, in this case advertiser_id field would be required
| Блок кода | ||
|---|---|---|
| ||
{
id: 1,
name: "<name>",
advertiser_id: 6
...
} |
API output
API output can be controlled by the following additional parameters and headers
Additional parameters controlling pagination/formatting
| Parameter | Description | Method | Values | Default | Example |
|---|---|---|---|---|---|
| mode | Affects on list's view. Old version: all collection will be returned at root (deprecated) New version: all collection will be placed to data node Value recommend to use always: 1 | all, list | 0 - old version (deprecated). 1 - new version. | 0 | ../list?token=<token>&mode=1 |
| custom_fields | Includes additional fields in "list" method output (by default "list" method returns only "id" and "name" fields) | list | CSV fields | null | ../list?token=<token>&custom_fields=<field1>,<field2>,... |
| page_limit | Items per one page. If "page_limit" parameter is used, then "mode" property's value becomes mode=1 automatically. | all, list | integer | null | ../list?token=<token>&page_limit=10 |
| page | Retrieves page [N] output, works only in case "page_limit" parameter is set. | all, list | integer | null | ../list?token=<token>&page_limit=10&page=2 |
| pretty | Controls JSON output format. | all,list | 0 - minimized JSON , 1 - formatted JSON | 0 | ../list?token=<token>&page_limit=10&pretty=1 |
Additional headers
| Parameter | Description | Available at, method | Values | By default | Example |
|---|---|---|---|---|---|
| if-modified-since | Returns "HTTP 304 Not Modified" header without content, if data has not been updated since requested date | list | Date in specify formatD, d M Y H:i:s GMT | null | if-modified-since: Fri, 18 Sep 2015 10:34:37 GMT |
| Блок кода | ||||
|---|---|---|---|---|
| ||||
{
"data": {
"921": {
"id": "921",
"name": "test_campaign"
},
"1400": {
"id": "1400",
"name": "1"
}
},
"pages": {
"total_elements": "6",
"total_pages": 3,
"current_page": 1,
"previous_page": false,
"next_page": 2,
"page_size": 2,
"offset": 0
}
} |