Шаблоны

Управление шаблонами осуществляется с помощью двух ресурсов:

  • /templates - ресурс для управления коллекцией шаблонов
  • /templates/:id - ресурс для управления конкретным шаблоном
Метод Ресурс Результат
POST /templates создать шаблон
GET /templates найти шаблоны
GET /templates/:id получить данные шаблона
POST /templates/:id изменить данные шаблона
DELETE /templates/:id удалить шаблон

Создание шаблона

Чтобы создать шаблон, необходимо выполнить запрос POST /template с JSON-документом в теле вида:

Поле Описание Обязателен Разрешенные значения
body Тело шаблона да
UTF8-текст.
Длина: 0-400 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{0,10000}$”
schema Схема шаблона Нет
JSON (формат см. ниже)
description Описание Нет
UTF8-текст.
Длина: 0-400 символов.
“^[\p{L}\p{P}\p{S}\p{N}\s]{0,10000}$”

schema - JSON-документ вида:

{
  <variable>: {
    type: <type>,
    required: <boolean>,
    regexp: <string>
    min_length: <int>,
    max_length: <int>,
    description: <string>,
    data: <object>
  }
}

<variable> - переменная из шаблона. <type> одно из следующих значений: any, array, boolean, integer, number, object, text, url, file

По умолчанию, обьявленная в схеме переменная считается обязательной к указанию (required: true).

Название переменное может содержать буквы, цифры и символ ‘_’.

Валидаторы ‘regexp’, ‘min_length’ и ‘max_length’ игнорируются, если указанный тип отличен от ‘text’.

Пример:

curl --request POST \
       --include \
       --user admin:admin \
       --header 'Content-Type: application/json' \
       --data \
       '{
              "body":"Hello, {{name}}!",
              "schema": {"name": {"type": "textarea","max_length":42}},
              "description":"Test template"
       }'\
       --url http://api.example.com/templates

 HTTP/1.1 200 OK
 Server: nginx/1.4.4
 Date: Wed, 04 Dec 2013 13:39:44 GMT
 Content-Type: application/json
 Content-Length: 124
 Connection: keep-alive
 Location: http://api.example.com/templates/1

 {
   "id":1,
   "body":"Hello, {{name}}!",
   "schema": {"name": {"type":"text", "max_length":42}},
   "description":"Test template"
 }

Только администраторы могут создавать шаблоны.

Предопределенные переменные

Переменная Описание
{{ click_url }} адрес перехода
{{ banner_id }} id баннера
{{ width }} ширина баннера
{{ height }} высота баннера

Поиск шаблонов

Чтобы получить список шаблонов, необходимо выполнить запрос GET /templates.

Пример:

$ curl --request GET \
       --include \
       --user admin:admin \
       --url http://api.example.com/templates

HTTP/1.1 200 OK
Server: nginx/1.4.4
Date: Wed, 04 Dec 2013 13:42:16 GMT
Content-Type: application/json
Content-Length: 138
Connection: keep-alive

{
  "results": [
    {
      "id":1,
      "body":"Hello, {{name}}!",
      "schema":{"name":{"type":"text","max_length":42}},
      "banners_count": 0,
      "description":"Test template"
    }
  ],
  "total_count": 1
}

Любой пользователь может искать шаблоны.

Получение данных шаблона

Чтобы получить данные шаблона, необходимо выполнить запрос GET /templates/:id.

Пример:

$ curl --request GET \
       --include \
       --user admin:admin \
       --url http://api.example.com/templates/1

HTTP/1.1 200 OK
Server: nginx/1.4.4
Date: Wed, 04 Dec 2013 13:43:36 GMT
Content-Type: application/json
Content-Length: 124
Connection: keep-alive

{
  "id":1,
  "body":"Hello, {{name}}!",
  "schema":{"name":{"type":"text","max_length":42}},
  "banners_count": 0,
  "description":"Test template"
}

Изменение данных шаблона

Чтобы изменить данные шаблона, необходимо выполнить запрос POST /templates/:id.

Формат документа для обновления данных шаблона идентичен формату документа для создания шаблона. Если поле не указано или содержит литерал null, значение поля не будет обновлено.

Пример:

$ curl --request POST \
       --include \
       --user admin:admin \
       --header 'Content-Type: application/json' \
       --data
       '{
         "body": "Bye, {{name}}!"
        }' \
       --url http://api.example.com/templates/1

HTTP/1.1 200 OK
Server: nginx/1.4.4
Date: Wed, 04 Dec 2013 13:44:35 GMT
Content-Type: application/json
Content-Length: 122
Connection: keep-alive

{
  "id":1,
  "body":"Bye, {{name}}!",
  "schema":{"name":{"type":"text","max_length":42}},
  "description":"Test template"
}

Удаление шаблона

Чтобы удалить шаблон, необходимо выполнить запрос DELETE /templates/:id.

Пример:

$ curl --request DELETE \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/templates/1

HTTP/1.1 204 No Content
Server: nginx/1.4.3
Date: Wed, 13 Nov 2013 11:20:35 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive

Только администраторы могут удалять шаблоны.