WAPI – Посібник

У цій статті ви дізнаєтеся:

• Як працює WAPI і для чого він призначений
• Як активувати WAPI в клієнтській адміністрації
• Як відбувається обмін даними та автентифікація
• Jak stránkovat a hledat v seznamech
• Основні команди
• Список кодів повернення
• Словник термінів

---

WEDOS API

WEDOS API, тобто WAPI, призначений для керування послугами безпосередньо з вашої інформаційної системи. 

Умовою використання інтерфейсу є користування Credit Account WEDOS, з якого система списує оплату за реєстрації, продовження (renewal), перереєстрації (transfer) та інші платні послуги.

Наразі WAPI дозволяє керувати:

• Credit Account ⧉ (account-* і credit-*)
• Доменами ⧉ (domains-* і domain-*)
• Контактами доменів ⧉ (contact-*)
• NSSET ⧉ (nsset-*)
• DNS ⧉ (dns-*)
• Уповноваженими користувачами WEDOS Global ⧉ (wg-members-*)
• WEDOS Protection ⧉ (wgp-services-* і wgp-domain-*)

Обмеження WAPI

Для захисту від зловживань WAPI застосовує такі обмеження:

• З одного облікового запису можна надіслати макс. 1000 запитів на годину. Це стосується всіх запитів усіх типів. Після досягнення цього ліміту WAPI відхиляє подальші запити до завершення часового ліміту.
• Один обліковий запис може надіслати макс. 100 запитів на перевірку доступності домену на годину. Це стосується команд domain-check, domain-create і domain-transfer-check.
• Повторне надсилання недійсних запитів (помилка авторизації, доступ із недозволеної IP-адреси, неправильні вхідні дані, відсутні або неправильні параметри, невідома команда, команди, що завершуються будь-якою помилкою, або будь-який запит поза рамками інших обмежень) призводить після перевищення 10 недійсних запитів до блокування IP-адреси на 1 хвилину за кожен недійсний запит. З кожним наступним помилковим запитом система збільшує тривалість блокування.

Синхронні та асинхронні операції

Більшість команд, що виконуються через WAPI, є синхронними: ви надсилаєте команду і, як правило, за кілька секунд дізнаєтеся результат. 

Деякі операції є асинхронними, тобто виконання такої команди може тривати дуже довго (навіть години або дні). Тому WAPI повертає не остаточний результат, а лише інформацію про прийняття команди. Інформацію про перебіг і остаточний результат система надсилає вам у формі сповіщень.

Журнал

Журнал запитів ви знайдете в клієнтській адміністрації за такими кроками:

1. Увійдіть до клієнтської адміністрації ⧉.
2. У верхньому меню виберіть My Account Customer.
3. У лівому меню виберіть WAPI requests.

---

Активація WAPI в клієнтській адміністрації

Перш ніж почати користуватися WAPI, активуйте його в клієнтській адміністрації за такими кроками:

1. Увійдіть до клієнтської адміністрації ⧉.
2. У верхньому меню виберіть My Account Customer.
3. У лівому меню виберіть WAPI interface.
4. Укажіть дозволені IP-адреси (IPv4 або IPv6, підтримується CIDR), спосіб сповіщень, бажаний протокол і пароль.
5. Підтвердіть налаштування кнопкою Set.

---

Обмін даними та автентифікація

Обмін даними з інтерфейсом WAPI відбувається через протокол HTTPS. Дані передаються методом POST у параметрі request у форматі XML або JSON. Базова форма команди та відповіді однакова для всіх команд. Кодування даних — UTF-8.

URL-адреси інтерфейсу:

• XML: https://api.wedos.com/wapi/xml
• JSON: https://api.wedos.com/wapi/json

Структура запиту

Запит складається з таких даних:

• user: Ім’я користувача (e-mail) вашого клієнтського облікового запису, обов’язковий параметр.
• auth: Авторизаційний рядок, обов’язковий параметр. Це sha1-хеш рядка, складеного з імені користувача, sha1-хешу пароля WAPI та поточної години (00-23). Часовий пояс — Europe/Prague (зимовий час UTC+1 CET, літній час UTC+2 CEST). Конкретний приклад дивіться в коді нижче.
• command: Власне команда WAPI. Обов’язковий параметр.
• clTRID: ID запиту, необов’язковий параметр. У цей елемент можна вписати будь-який рядок як ідентифікатор, який WAPI поверне у відповіді.
• data: Дані команди. Необов’язковий параметр.
• test: Ознака тестового режиму, необов’язковий параметр. Якщо ви додасте до команди елемент test зі значенням 1, WAPI лише перевірить вашу команду, але не виконуватиме жодних змін.

Отже, шаблон запиту (JSON) такий:

{
  "request":
  {
    "user": "ваш@login.tld",
    "auth": "авторизаційний рядок",
    "command": "назва запиту",
    "data":
    {
      дані запиту
    }
    "clTRID": "ідентифікатор запиту (необов'язково)",
    "test": "1 (якщо ви хочете лише протестувати запит, необов'язково)"
  }
}

Повний приклад використання в PHP (формат даних JSON) може виглядати так:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'ваш@login.tld'; 
$wpass = 'ваш пароль до WAPI'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'назва запиту',
  'data' => ['масив даних запиту'],
  'clTRID' => 'ідентифікатор запиту (необов'язково)',
  'test' => '1 (якщо ви хочете лише протестувати запит)'
  ]
];

$post = json_encode($input);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_TIMEOUT,60);
curl_setopt($ch,CURLOPT_POST,true);
curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . urlencode($post));
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>

Структура відповіді

Відповідь складається з таких даних:

• code: Значення, яке повертає команда. Докладніше дивіться в розділі Коди повернення.
• result: Текстовий опис коду повернення.
• timestamp: Час виконання команди у форматі UNIX.
• clTRID: Ідентифікатор команди з боку клієнта.
• svTRID: Ідентифікатор команди на стороні сервера.
• command: Команда WAPI.
• data: Значення, що повертаються. Якщо команда завершується помилкою, дані не повертаються.
• test: Додається у відповідь на команди, які також містять цю ознаку.

Приклад відповіді у форматі JSON виглядає, наприклад, так:

{
  "response":
  {
    "code": "1000",
    "result": "ok",
    "timestamp": "1286356644",
    "svTRID": "1286356644.0246.21616",
    "command": "domain-create",
    "data": 		
    {
      "num": "1311000863",
      "expiration": "2011-10-06"
    },
    "test": "1"
  }
}

Stránkování a hledání v seznamech

Seznamové příkazy domains-list і dns-rows-list mají nepovinné parametry pro hledání a stránkování. Když je nezadáte, WAPI vrátí odpověď stejně jako dosud, tedy celý seznam.

Parametry v části data požadavku:

• search: Hledaný text, bez rozlišení velikosti písmen. U domains-list se hledá v názvu domény, u dns-rows-list v názvu nebo datech záznamu.
• page: Číslo stránky od 1. Výchozí hodnota je 1.
• page_limit: Počet položek na stránku, nejvýše 1000 (větší hodnotu WAPI sníží na 1000). Když ho nezadáte nebo zadáte 0, WAPI vrátí všechny položky.

Команда dns-rows-list má navíc tyto filtry:

• row_name: Přesný název záznamu. Hodnota @ znamená záznam přímo na doméně.
• rdtype: Typ záznamu (A, AAAA, MX, TXT…), na velikosti písmen nezáleží.

Když zadáte kterýkoli z těchto parametrů, WAPI vrátí seznam jako pole (u domains-list v položce domain, u dns-rows-list v položce row) a v části data odpovědi doplní:

• total: Celkový počet položek po použití filtrů.
• page: Číslo vrácené stránky.
• page_limit: Použitý počet položek na stránku (0 znamená všechny).

Na co dát pozor:

• Stránka za koncem seznamu vrátí prázdný seznam s položkou total, ne chybu.
• Neplatnou hodnotu page або page_limit (text, záporné číslo) WAPI neodmítne, ale nahradí ji výchozí hodnotou: page 1, page_limit 0, tedy všechny položky.
• Pole místo hodnoty v page або page_limit vrátí chybu 2101.
• Команда dns-domains-list vrací total (jako řetězec), page і page_limit vždy. Když page_limit nezadáte nebo zadáte 0, použije 1000.

Команда JSON domains-list (aktivní domény obsahující „example“, první stránka po dvou doménách), podrobný popis v dokumentaci příkazu domains-list ⧉:

{
  "request": {
    "user": "ваш@login.tld",
    "auth": "згенерований авторизаційний рядок",
    "command": "domains-list",
    "clTRID": "власний id-код",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

Команда JSON dns-rows-list (záznamy typu A domény example.cz, první stránka po 50 záznamech), podrobný popis v dokumentaci příkazu dns-rows-list ⧉:

{
  "request": {
    "user": "ваш@login.tld",
    "auth": "згенерований авторизаційний рядок",
    "command": "dns-rows-list",
    "clTRID": "власний id-код",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Сповіщення

Асинхронні операції неможливо виконати миттєво. Перебіг і результат таких операцій можна відстежувати за допомогою сповіщень. Синхронні запити сповіщень не використовують.

Якщо WAPI не може завершити операцію одразу, у відповіді він повертає Request pending (1001). Після завершення операції (у складніших діях — кожного кроку) створюється сповіщення, яке є аналогом звичайної відповіді. Сповіщення можна зіставити з відповідним запитом за параметрами clTRID або svTRID.

Дані сповіщення завжди мають кодування UTF-8.

Сповіщення можна отримувати такими способами (залежно від налаштувань під час активації):

• Через чергу POLL.
• Надсилання на вказану адресу електронної пошти.
• Через протокол HTTP (або HTTPS) на визначену вами URL-адресу методом POST у параметрі request. Коректною доставкою вважається HTTP-відповідь із кодом повернення 200. Якщо доставити не вдасться, наша система повторюватиме спроби доставки з інтервалом у кілька хвилин.

Приклад сповіщення у форматі JSON виглядає, наприклад, так:

{
  "notify": {
    "code": 1000,
    "result": "OK",
    "timestamp": 1286957932,
    "clTRID": "AvrX87Kqk6h3",
    "svTRID": "1286957874.1271.15706",
    "command": "ping-async",
    "ID": 2691
  }
}

Системні сповіщення

Системні сповіщення надсилають інформацію про важливі події, наразі лише про перереєстрацію (transfer) домену до іншого реєстратора. Якщо у вашому обліковому записі активовано WAPI, система надішле таку інформацію у вигляді сповіщення, подібно до асинхронної команди.

Протокол, у якому WAPI надсилає системні сповіщення, налаштуйте за розділом Активація WAPI в клієнтській адміністрації. Цей параметр діє для сповіщень, що надсилаються на e-mail або URL-адресу. У разі отримання з черги POLL відповідь має таку саму форму, як і команда.

Структура така сама, як у звичайного сповіщення, команда (command) завжди system-notify. У вузлі data ви знайдете докладнішу інформацію.

---

Основні команди

До основних команд належать ping, ping-async та команди для роботи з чергою POLL poll-req і poll-ack.

ping

Команда ping призначена для перевірки працездатності WAPI — наприклад, облікових даних, IP-адреси або коду.

Значення, що повертаються:

• 1000 – OK

Команда JSON:

{
  "request": {
    "user": "ваш@login.tld",
    "auth": "згенерований авторизаційний рядок",
    "command": "ping",
    "clTRID": "власний id-код"
  }
}

Відповідь JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF час",
    "clTRID": "власний id-код",
    "svTRID": "id-код сервера",
    "command": "ping"
  }
}

ping-async

Команда ping-async перевіряє працездатність сповіщень WAPI.

Значення, що повертаються:

• 1000 OK
• 1001 Очікування команди

Команда JSON:

{
  "request": {
    "user": "ваш@login.tld",
    "auth": "згенерований авторизаційний рядок",
    "command": "ping",
    "clTRID": "власний id-код"
  }
}

Відповідь JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF час",
    "clTRID": "власний id-код",
    "svTRID": "id-код сервера",
    "command": "ping"
  }
}

Сповіщення JSON:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF час",
    "clTRID": "власний id-код",
    "svTRID": "id-код сервера",
    "command": "ping-async",
    "id": "id для черги POLL",
    "data": {
      "round": "номер спроби",
      "time": "час",
      "done": 1
    }
  }
}

poll-req і poll-ack

Сповіщення з черги POLL ви отримуєте комбінацією команд poll-req і poll-ack: 

1. Командою poll-req ви завантажуєте найстаріше доступне сповіщення.
2. Командою poll-ack ви позначаєте сповіщення як отримане і тим самим відкриваєте доступ до новіших, доки черга не вичерпається.

Значення, що повертаються для poll-req:

• 1000 – сповіщення отримано
• 1003 – у черзі немає жодного непрочитаного сповіщення
• 2150 – у вашому обліковому записі не налаштовано отримання сповіщень із черги POLL

Команда JSON poll-req:

{
  "request": {
    "user": "ваш@login.tld",
    "auth": "згенерований авторизаційний рядок",
    "command": "poll-req",
    "clTRID": "власний id-код"
  }
}

Відповідь JSON на poll-req (сповіщення доступне):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF час",
    "clTRID": "власний id-код",
    "svTRID": "id-код сервера",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF час",
        "clTRID": "власний id-код знайденої команди",
        "svTRID": "id-код сервера для знайденої команди",
        "command": "назва команди",
        "id": "id у черзі POLL"
      }
    }
  }
}

Відповідь JSON на poll-req (порожня форма сповіщень):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "власний id-код",
    "svTRID": "id-код сервера",
    "command": "poll-req"
  }
}

Для команди poll-ack ви вказуєте дані (параметри):

• id – ID поточного сповіщення POLL

Значення, що повертаються для poll-ack:

• 1002 – сповіщення позначено як отримане
• 2151 – сповіщення не знайдено

Команда JSON poll-ack:

{
  "request": {
    "user": "ваш@login.tld",
    "auth": "згенерований авторизаційний рядок",
    "command": "poll-ack",
    "clTRID": "власний id-код",
    "data": {
      "id": “ID отриманого сповіщення POLL”
    }
  }
}

Відповідь JSON на poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF час",
    "clTRID": "власний id-код",
    "svTRID": "id-код сервера",
    "command": "poll-ack"
  }
}

---

Список кодів повернення

Коди повернення у відповідях і сповіщеннях допоможуть вам визначити перебіг роботи WAPI та можливі помилки.

Основний поділ кодів повернення:

• 1xxx – команду виконано успішно.
• 2xxx – неправильна команда (наприклад, відсутні вхідні поля, їхній неправильний формат або значення).
• 3xxx – помилка цільового об’єкта – неможливо виконати потрібну дію, об’єкт перебуває в неправильному стані (наприклад, під час спроби зареєструвати вже зайнятий домен тощо).
• 4xxx – помилка під час виконання команди (наприклад, недоступність реєстру доменів, помилка зв’язку тощо).
• 5xxx – внутрішня помилка або стан нашої системи.
• x0xx, x1xx – загальні.
• x2xx – домени.
• x3xx – DNS.

Конкретні відповіді, що повертаються на певну команду, завжди дивіться в документації до цієї команди.

---

Словник термінів

• Асинхронна команда: Команда, що виконується тривалий час, повертає лише повідомлення про прийняття, подальший перебіг ви відстежуєте за допомогою сповіщень.
• API: Application Programming Interface. Інтерфейс, який дає змогу власним кодом отримувати дані або керувати стороннім застосунком.
• Дані: Вміст деяких команд, що визначає детальні налаштування. Структура даних залежить від конкретної команди.
• JSON: JavaScript Object Notation. Сучасний спосіб обміну даними з API.
• Код повернення: Число, що визначає тип відповіді WAPI на команду.
• Сповіщення: Код JSON або XML із повідомленнями про перебіг асинхронної команди.
• Команда: Запит до WAPI.
• Синхронна команда: Команда, що виконується практично миттєво. Повертає повноцінну відповідь, не використовує сповіщення.
• Системні сповіщення: Особливий вид сповіщень про події в системі, WAPI надсилає їх автоматично в налаштованому форматі.
• UTF-8: Unicode Transformation Format. Поширений міжнародний стандарт кодування символів, що підтримує велику кількість писемностей.
• WAPI: Інтерфейс для керування деякими частинами клієнтської адміністрації (Credit Account, домени, DNS).
• XML: eXtended Markup Language. Старіший спосіб обміну даними з API.

Чи була ця стаття корисною?

Ваша оцінка допомагає нам покращувати статті.

ТакНі

Хочете щось повідомити нам про цю статтю? (необов’язково)

Ваше повідомлення прочитає редакція документації, але вона на нього не відповідає. Якщо вам потрібна допомога, звертайтеся до нас через контактну форму. Не вказуйте тут паролі чи особисті дані.

Не заповнюйте це поле