Skip to content

Commit

Permalink
REST API: edits and clarifications
Browse files Browse the repository at this point in the history
  • Loading branch information
enclaved committed Dec 7, 2022
1 parent 7b533be commit e793235
Show file tree
Hide file tree
Showing 2 changed files with 127 additions and 128 deletions.
253 changes: 126 additions & 127 deletions api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,116 @@ $authKey = base64_encode($apiKey . ':');
относительно этого базового URL. Сначала указан HTTP-метод, за которым следует относительный путь точки вызова.
Например, описание точки вызова `GET /streams` означает GET-запрос на URL `https://api.adspect.net/v1/streams`.

## Коллекции

Некоторые свойства объектов могут принимать значения только из строго заданных множеств --- коллекций.
Ниже приводятся списки таких значений и точки доступа для их программного получения.

### Операционные системы

Названия операционных систем (не чувствительны к регистру):

* `Android 1`
* `Android 2`
* `Android 3`
* `Android 4`
* `Android 5`
* `Android 6`
* `Android 7`
* `Android 8`
* `Android 9`
* `Android 10`
* `Android 11`
* `Android 12`
* `Android 13`
* `iOS`
* `KaiOS`
* `macOS`
* `Linux`
* `Other`
* `Windows XP`
* `Windows Vista`
* `Windows 7`
* `Windows 8`
* `Windows 8.1`
* `Windows 10`
* `Windows Other`

Получение списка названий операционных систем:

```
GET /collections/os
```

### Браузеры

Названия браузеров (не чувствительны к регистру):

* `Apple Safari`
* `Facebook app`
* `Google Chrome`
* `Internet Explorer`
* `Microsoft Edge`
* `Mozilla Firefox`
* `Opera`
* `Other`
* `Samsung Internet`
* `Snapchat app`
* `UC Browser`
* `WebView`
* `Yandex Browser`

Получение списка названий браузеров:

```
GET /collections/browsers
```

### Движки браузера

Названия движков браузера (не чувствительны к регистру):

* `Blink`
* `EdgeHTML`
* `Gecko`
* `Other`
* `Presto`
* `Trident`
* `WebKit`

Получение списка названий движков браузера:

```
GET /collections/engines
```

### Коды стран

Получение списка кодов стран:

```
GET /collections/countries
```

### Коды языков

Получение списка кодов языков:

```
GET /collections/languages
```

### Часовые пояса

Получение списока часовых поясов:

```
GET /collections/time-zones
```

## Управление потоками

Каждый поток представляется в виде объекта, который содежит следующие свойства:
Поток представляется в виде объекта со следующими свойствами:

* `stream_id` --- ID потока, только для чтения;
* `account_id` --- ID аккаунта, только для чтения;
Expand Down Expand Up @@ -111,8 +218,10 @@ $authKey = base64_encode($apiKey . ':');
{
"stream_id": "1eacc6d0-875f-6f5c-bff8-00162501c2b4",
"account_id": "1eaa2ce5-d4dd-63ec-b8a4-00162501c2b4",
"name": "Example stream",
"name": "Example Stream",
"tags": ["Tag1", "Tag2"],
"mode": "Filter",
"notes": "This is just an example.",
"money_pages": [
{
"page": "https://example.com/offer1?clid={clickid}",
Expand Down Expand Up @@ -256,20 +365,19 @@ DELETE /streams/<id>

1. Создается сохраненный запрос к статистике, в котором указываются параметры выгрузки отчета (даты и фильтры);
2. В ответ API передает ID сохраненного запроса;
3. Гость может выполнить этот сохраненный запрос (либо его подмножество) без входа в систему на странице
https://clients.adspect.ai/reporting, указав ID сохраненного запроса в соответствующем поле, либо перейдя
по ссылке вида `https://clients.adspect.ai/reporting?query_id=<id>`, где вместо `<id>` подставляется
ID сохраненного запроса.
3. Гость может выполнить этот сохраненный запрос на [странице статистики](https://clients.adspect.ai/reporting),
указав ID сохраненного запроса в соответствующем поле, либо перейдя по ссылке вида
`https://clients.adspect.ai/reporting?query_id=<id>`, где вместо `<id>` подставляется ID сохраненного запроса.

Каждый сохраненный запрос представляется в виде объекта, который содежит следующие свойства:
Сохраненный запрос представляется в виде объекта со следующими свойствами:

* `query_id` --- ID сохраненного запроса в формате UUID, только для чтения;
* `owner_id` --- ID аккаунта-владельца в формате UUID, только для чтения;
* `query_id` --- ID сохраненного запроса, только для чтения;
* `owner_id` --- ID аккаунта владельца, только для чтения;
* `date_from` --- минимальное Unix-время, начиная с которого выгружается отчет;
* `date_to` --- максимальное Unix-время, до которого выгружается отчет;
* `time_zone` --- часовой пояс по умолчанию, используемый для отображения даты и времени;
* `group_by` --- группировка воронки продаж по умолчанию;
* `account_id` --- фильтр по ID аккаунтов, массив строк;
* `account_id` --- фильтр по ID аккаунтов, массив строк, только для чтения;
* `stream_id` --- фильтр по ID потоков, массив строк;
* `ip_address` --- фильтр по IP-адресам, массив строк;
* `asn` --- фильтр по ASN, массив целых чисел, либо строк вида "AS65536" или "AS1.10";
Expand All @@ -279,7 +387,7 @@ DELETE /streams/<id>
* `engine` --- фильтр по движкам, массив строк;
* `sub_id` --- фильтр по субаккаунтам, массив строк;
* `click_id` --- фильтр по ID переходов, массив строк;
* `mode` --- фильтр по режиму потока, массив строк: `Filter`, `Review`, `Money`, `White`;
* `mode` --- фильтр по режиму потока, массив строк из списка: `Filter`, `Review`, `Money`, `White`;
* `target` --- фильтр по показанной странице, массив целых чисел:
* 0 --- белая страница;
* 1 и выше --- контент-страница с соответствующим номером.
Expand All @@ -291,11 +399,11 @@ DELETE /streams/<id>

```json
{
"query_id": "878efbf1-0fb9-4c69-ad36-40e714b0eeeb"
"query_id": "878efbf1-0fb9-4c69-ad36-40e714b0eeeb",
"owner_id": "1eb5991f-a25b-68f4-b171-00162501c2b4",
"date_from": 1577836800,
"date_to": null,
"time_zone": "UTC",
"time_zone": "Asia/Dubai",
"group_by": [],
"account_id": ["1eb5991f-a25b-68f4-b171-00162501c2b4"],
"stream_id": ["6792f6ce-f153-439f-b223-f58749f1210f"],
Expand All @@ -308,7 +416,7 @@ DELETE /streams/<id>
"sub_id": [],
"click_id": [],
"mode": ["Filter"],
"target": [],
"target": []
}
```

Expand Down Expand Up @@ -354,17 +462,15 @@ GET /reports/<id>
POST /reports
```

Эта точка вызова создает и возвращает новый запрос. Укажите объект запроса в теле запроса.
Все свойства объекта запроса имеют значения по умолчанию, поэтому вам нужно указывать только те свойства,
значения которых вы хотите задать явно, например `{"name":"My Stream"}`.
Эта точка вызова создает и возвращает новый запрос. Укажите объект запроса в теле HTTP-запроса.

### Обновление запроса

```
PATCH /reports/<id>
```

Эта точка вызова обновляет запрос `<id>`. Укажите объект запроса в в теле запроса.
Эта точка вызова обновляет запрос `<id>`. Укажите объект запроса в теле HTTP-запроса.
Вам нужно указать только те свойства, значения которых вы хотите изменить; все остальные свойства
останутся неизменными.

Expand All @@ -374,9 +480,9 @@ PATCH /reports/<id>
COPY /reports/<id>
```

Эта точка вызова копирует запрос `<id>`. Укажите объект запроса в теле запроса ---
Эта точка вызова копирует запрос `<id>`. Укажите объект запроса в теле HTTP-запроса ---
указанные в нем свойства заменят свойства в скопированном запросе, что сэкономит вам дополнительный
вызов точки `PATCH`. Если свойства изменять не требуется, то укажите пустой объект `{}`.
вызов точки `PATCH`.

### Удаление запроса

Expand All @@ -385,110 +491,3 @@ DELETE /reports/<id>
```

Эта точка вызова удаляет запрос `<id>`.

## Коллекции

Некоторые свойства объектов могут принимать значения только из строго заданных множеств --- коллекций.
Ниже приводятся списки таких значений и точки доступа для их программного получения.

### Операционные системы

Названия операционных систем (не чувствительны к регистру):

* `Android 1`
* `Android 2`
* `Android 3`
* `Android 4`
* `Android 5`
* `Android 6`
* `Android 7`
* `Android 8`
* `Android 9`
* `Android 10`
* `Android 11`
* `Android 12`
* `Android 13`
* `iOS`
* `KaiOS`
* `macOS`
* `Linux`
* `Other`
* `Windows XP`
* `Windows Vista`
* `Windows 7`
* `Windows 8`
* `Windows 8.1`
* `Windows 10`
* `Windows Other`

Получение списка названий операционных систем:

```
GET /collections/os
```

### Браузеры

Названия браузеров (не чувствительны к регистру):

* `Apple Safari`
* `Facebook app`
* `Google Chrome`
* `Internet Explorer`
* `Microsoft Edge`
* `Mozilla Firefox`
* `Opera`
* `Other`
* `Samsung Internet`
* `Snapchat app`
* `UC Browser`
* `WebView`
* `Yandex Browser`

Получение списка названий браузеров:

```
GET /collections/browsers
```

### Движки браузера

Названия движков браузера (не чувствительны к регистру):

* `Blink`
* `EdgeHTML`
* `Gecko`
* `Other`
* `Presto`
* `Trident`
* `WebKit`

Получение списка названий движков браузера:

```
GET /collections/engines
```

### Коды стран

Получение списка кодов стран:

```
GET /collections/countries
```

### Коды языков

Получение списка кодов языков:

```
GET /collections/languages
```

### Часовые пояса

Получение списока часовых поясов:

```
GET /collections/time-zones
```
2 changes: 1 addition & 1 deletion conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
# -- Project information -----------------------------------------------------

project = u'Adspect'
copyright = u'2019‒2021, Adspect'
copyright = u'2019‒2022, Adspect'
author = u'Adspect'

# The short X.Y version
Expand Down

0 comments on commit e793235

Please sign in to comment.