WAPI – Manual

In this article, you will learn:

• How WAPI works
  • Supported services
  • Request restrictions
  • Synchronous and asynchronous requests
  • Response codes
• How to activate WAPI in the WEDOS Global admin panel
• How to integrate WAPI to your system
• Basic requests to test WAPI features
• Troubleshooting common issues
• Frequently asked questions

---

WEDOS API (WAPI)

The WEDOS API, WAPI for short, is used to manage WEDOS services directly from your system via requests and responses.

• Communication is either synchronous (odgovor je običajno obdelan v nekaj sekundah po prejemu zahteve) ali asynchronous (nekateri odgovori lahko trajajo dlje; postopek se spremlja prek obvestil).
• Data is passed via the HTTPS protocol by the POST method in the request parameter; data encoding is UTF-8.
• Supported formats include both XML and JSON.

Supported Services

WAPI currently supports the following WEDOS Global services:

• WEDOS Global Members
• WEDOS Protection
• WEDOS DNS and NSSET

Additionally, you can access WEDOS domain registrar services:

• Domains
• Domain contacts
• Credit account

WAPI Restrictions

To protect against misuse, WAPI applies the following restrictions:

• One user account can send a maximum of 1000 requests per hour. This applies to all types of requests. When this limit is reached, WAPI rejects further requests until the timeout expires.
• One user account is allowed to make a maximum of 100 domain availability requests per hour. This applies to the domain-check, domain-create and domain-transfer-check requests.
• Repeated invalid requests (neuspešna avtorizacija, dostop z nepooblaščenega naslova IP, napačen vnos, manjkajoči ali napačni parametri, neznani ukazi, ukazi, ki povzročijo kakršno koli napako, ali katera koli zahteva zunaj drugih omejitev) bo povzročila blokado naslova IP za 1 minuto za vsako neveljavno zahtevo nad 10. Z vsako dodatno neveljavno zahtevo sistem podaljša čas blokade.

Synchronous and asynchronous requests

Most of the requests executed via WAPI are synchronous – you send the request and you usually get the result within a few seconds.

Some requests are asynchronous – processing such requests can take a very long time (even hours or days). In such cases, WAPI doesn’t return the final result, but only information about receiving the request. The system then sends you information about the progress and the final result in the form of notifications.

Response codes

Response codes indicate the status of a WAPI response. Some codes are request-specific and can be found in the corresponding WAPI documentation; the list below applies to all requests.

• 1000 OK
• 2000 Napaka pri razčlenjevanju zahteve
• 2001 Neveljavna zahteva – manjka obvezni parameter: user
• 2002 Neveljavna zahteva – manjka obvezni parameter: auth
• 2003 Neveljavna zahteva – manjka obvezni parameter: command
• 2004 Neveljavna zahteva – dovoljen je samo en element data
• 2005 Neveljavna zahteva – parameter clTRID je predolg
• 2006 Omejitev števila zahtev presežena
• 2007 Neveljavna zahteva – presežena največja velikost zahteve
• 2008 Neveljavna zahteva – zahteva je preveč zapletena
• 2009 Neveljavna zahteva – zahteva je prazna
• 2010 Neznan ukaz
• 2011 = Ukaz je onemogočen
• 2050 = Napaka pri avtentikaciji
• 2051 = Dostop s tega naslova IP ni dovoljen
• 2052 Naslov IP je začasno blokiran zaradi preveč neuspešnih zahtev
• 2100 Manjka obvezni parameter
• 2101 Parametri se ne ujemajo
• 2102 Neveljavna zahteva – kodiranje vhodnih podatkov se ne ujema
• 4000 Notranja napaka
• 4001 Notranja izjema
• 5000 Usodna napaka
• 5001 Notranja napaka pri avtentikaciji
• 5003 Izven obratovanja

---

Aktivacija WAPI

Preden lahko začnete uporabljati WAPI, ga morate aktivirati. Sledite tem korakom:

1. Log into the WEDOS Global admin panel ⧉.
2. In the left bar, select WAPI.
3. In the WAPI Setup form, enter the following and confirm using the Set button:
   • Allowed IPs: A comma-separated list of IP addresses (both IPv4 and IPv6, supports CIDR notation) from which your system connects to WAPI.
   • Notification Mode: Način prejemanja obvestil o poteku asinhronih zahtev.
   • Preferred Protocol: This setting only applies to system notifications. Responses use the same format as requests.
4. In the Password Settings form, enter the WAPI password (twice to confirm it) and click the Set button.

The settings will take effect within 30 minutes.

---

Integrate WAPI into Your System

To integrate WAPI into your system once it’s been activated, you need to:

• Set up a script to connect to the API
• Send a request
• Receive and process a response
• Receive and process a notification

Connect to WAPI

To connect your system to WAPI, you will need:

• Your WEDOS login email and WAPI password
• The WAPI URL (depends on format):
  • XML: https://api.wedos.com/wapi/xml
  • JSON: https://api.wedos.com/wapi/json

WAPI takes a single authentication string, which is a SHA-1 hash of a string composed of the username, the SHA-1 hash of the WAPI password and the current time (00-23). The time zone is Europe/Prague (UTC+1 CET, or UTC+2 CET with DST adjustment). See code below for a specific example.

The following template demonstrates connecting to WAPI using a PHP script:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'your@login.tld'; 
$wpass = 'your-WAPI-password'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'request name',
  'data' => ['request data'],
  'clTRID' => 'request identifier',
  'test' => '1 (if you only want to test the request)'
  ]
];

$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);
curl_close($ch);
?>

WAPI Request

Zahteva WAPI je sestavljena iz naslednjih podatkov:

• test: Zastavica testnega načina, neobvezna. Če v zahtevo vključite element test z vrednostjo 1, bo WAPI ukaz le preveril, v sistemu pa ne bo naredil nobenih sprememb.
• user: Prijava v vaš uporabniški račun WEDOS (e-naslov), obvezno.
• auth: Avtorizacijski niz, obvezen. To je zgoščena vrednost SHA-1 niza, sestavljenega iz uporabniškega imena, zgoščene vrednosti SHA-1 gesla WAPI in trenutnega časa (00–23). Časovni pas je Europe/Prague (UTC+1 CET oziroma UTC+2 CET s popravkom za poletni čas). Konkreten primer je v kodi spodaj.
• command: Dejanska zahteva WAPI. Obvezno.
• clTRID: ID zahteve, neobvezen. V ta element lahko vpišete poljuben niz kot identifikator, ki ga bo WAPI vrnil v odgovoru.
• data: Podatkovni del zahteve. Neobvezno.

The following is a template JSON request:

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "auth-string",
    "command": "request-name",
    "data":
    {
      request data
    }
    "clTRID": "request-id (optional)",
  }
}

WAPI Response

The response consists of the following data:

• code: Povratna vrednost za dano zahtevo. Več informacij o teh kodah najdete v Response codes section and specific command documentation.
• result: Opis povratne kode.
• timestamp: Čas izvedbe ukaza v obliki UNIX.
• clTRID: Identifikator zahteve odjemalca.
• svTRID: Identifikator zahteve strežnika.
• command: Zahteva WAPI.
• data: Vrnjeni podatki. Brez, če zahteva ne uspe.
• test: Vključeno v odgovore na testne zahteve.

The following is a template JSON response:

{
  "response": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "request-name"
  }
}

Notifications

Asynchronous requests cannot be performed immediately. You can monitor the progress and result of such operations through notifications. Synchronous requests do not use notifications.

If WAPI cannot complete the operation immediately, it returns Request pending (1001) in response. After the operation is completed (for more complicated actions of individual steps), it creates a notification that is similar to a classic response. You can match the notification to the corresponding request using the clTRID or svTRID parameters.

Notification data is always encoded in UTF-8.

You can receive notifications in the following ways (according to the settings):

• Using the POLL queue.
• Send to specified email address.
• Via HTTP (or HTTPS) protocol to the URL address specified by you using the POST method in the request parameter. An HTTP response with a return code of 200 is considered a success. If delivery fails, the system will attempt to deliver the notification againat several-minute intervals.

The following is a template JSON notification:

{
  "notify": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "svTRID": "server request id",
    "command": "request-name",
    "ID": "numerical id"
  }
}

---

Basic Requests

Basic requests include ping, ping-async, in ukazi za delo z vrsto POLL poll-req and poll-ack.

ping

The ping request is used to test WAPI functionality – for example, login credentials, IP address or code.

The return values are:

• 1000 – OK

JSON request template:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "clTRID": "user request id"
  }
}

JSON response template:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

ping-async

The ping-async request tests the functionality of WAPI notifications.

The return values are:

• 1000 – OK
• 1001 – Čakanje na zahtevo

JSON request template:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping-async",
    "clTRID": "user request id"
  }
}

JSON response template:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async"
  }
}

JSON notification template:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async",
    "id": "poll queue id",
    "data": {
      "round": "attempt number",
      "time": "time",
      "done": 1
    }
  }
}

poll-req and poll-ack

You can receive notifications from the POLL queue by combining poll-req and poll-ack commands:

1. Use the poll-req command to download the oldest available notification.
2. With the poll-ack command, mark the notification as read and make newer ones available until the queue is exhausted.

The return values for poll-req are:

• 1000 – obvestilo prejeto
• 1003 – v vrsti ni neprebranih obvestil
• 2150 – obvestila vrste poll so za ta račun onemogočena

JSON poll-req request template:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-req",
    "clTRID": "user request id"
  }
}

JSON poll-req response template (notification available):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF time",
        "clTRID": "request user id",
        "svTRID": "request server id",
        "command": "request name",
        "id": "poll queue id"
      }
    }
  }
}

JSON poll-req response template (empty notification queue):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req"
  }
}

Include the following parameters in the poll-ack request:

• id – current poll notification ID

The return values for poll-ack are:

• 1002 – obvestilo označeno kot prebrano
• 2151 – obvestilo ni najdeno

JSON poll-ack request:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-ack",
    "clTRID": "user request id",
    "data": {
      "id": “poll notification id”
    }
  }
}

JSON poll-ack response:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-ack"
  }
}

---

Troubleshooting Common Issues

Common issues with WAPI include:

• Failing to authenticate requests

---

FAQ

Ali vam je bil ta članek v pomoč?

Vaše mnenje nam pomaga izboljšati naše članke.

DaNe

Bi nam radi sporočili kaj o tem članku? (neobvezno)

Vaše sporočilo prejme ekipa za dokumentacijo, ki nanj ne odgovarja. Če potrebujete pomoč, nas kontaktirajte prek kontaktnega obrazca. Ne vpisujte gesel ali osebnih podatkov.

Tega polja ne izpolnjujte