WAPI – podstawy komunikacji, autoryzacja

Komunikacja z interfejsem WAPI odbywa się za pośrednictwem protokołu HTTPS. Dane są przekazywane przy użyciu metody POST w parametrze request. Dane są w formacie XML. Podstawowa forma zapytania i odpowiedzi jest taka sama dla wszystkich poleceń. Zapytania są przetwarzane w kodowaniu UTF-8.

Adresy URL interfejsu:

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

Zapytanie

<request>
<user>tester</user>
<auth>202b62bc4646281f97d225db1249840c8452dd8f</auth>
<command>domain-create</command>
<clTRID>a44B</clTRID>
<data>
<name>example.cz</name>
<period>1</period>
<dns></dns>
<owner_c>CONTACT</owner_c>
<admin_c>CONTACT</admin_c>
</data>
<test>1</test>
</request>

user

Login twojego konta klienta, parametr obowiązkowy.

auth

Łańcuch autoryzacji używany do autoryzacji zapytania, parametr obowiązkowy.

Chodzi tu o łańcuch sha1 hash składający się z Twojego loginu, sha1 hashe hasła konta WAPI i aktualnej godziny (00-23). Strefa czasowa to Europa / Praga (czas zimowy UTC+1 CET, czas letni UTC+2 CEST). Łańcuch autoryzacji tester, z hasłem WAPI 123456, wysłany o 11:30 będzie przed ostatecznym haszowaniem wyglądać następująco:

tester7c4a8d09ca3762af61e59520943dc26494f8941b11

a po użyciu funkcji sha1 w następujący sposób:

ac28237e80e68efa3bfd07f42dca3d41c5986e01

Na przykład utworzenie łańcucha autoryzacji w języku PHP wygląda następująco:

$auth = sha1($login.sha1($wpass).date('H', time()));

command

Godzinę należy zawsze wprowadzać za pomocą dwóch cyfr.

polecenie WAPI. Parametr obowiązkowy.

clTRID

ID żądania, parametr opcjonalny.

W tym elemencie możesz umieścić dowolny łańcuch. Jeśli to zrobisz, identyfikator ten zostanie zwrócony w odpowiedzi. Służy do identyfikowania pojedynczych żądań, szczególnie dla poleceń asynchronicznych (wykonywanych z opóźnieniem), w których odpowiedź nie jest zwracana natychmiast, a w przypadku dużej liczby operacji nie byłoby możliwe odróżnienie, która odpowiedź należy do którego zapytania.

data

Część zapytania z danymi. Parametr opcjonalny.

Jeśli polecenie wymaga przekazania pewnych informacji (w przypadku domen najczęściej jest to nazwa domeny), są one wstawiane do tego elementu. Dla każdego polecenia opisano dokładnie, jakie dane, w jakim formacie należy przekazać.

test

Flaga trybu testowego, parametr opcjonalny.

Jeśli w zapytaniu umieścisz element test o wartości 1, system tylko skontroluje Twoje zapytanie, ale nie wprowadzi żadnych zmian. Flaga ta służy do testowania systemów przez ich wdrożeniem.

Odpowiedź

Każde zapytanie WAPI zawsze zwraca odpowiedź XML, która zawiera co najmniej elementy code i result. W polu code zwracany jest kod powrotu odpowiedzi, a w polu result jego opis tekstowy. Kody powrotu są podzielone na kategorie:

  • 1xxx – polecenie wykonane pomyślnie.
  • 2xxx – nieprawidłowe zapytanie (na przykład brakujące elementy wejściowe,ich niepoprawny format lub wartość).
  • 3xxx – błąd obiektu docelowego – nie można wykonać żądanej akcji, obiekt nie posiada odpowiedniego statusu (na przykład przy próbie rejestracji zajętej już domeny, …).
  • 4xxx – błąd przy wykonywaniu polecenia (np. niedostępność rejestru domen, błąd komunikacji).
  • 5xxx – status lub błąd wewnętrzny naszego systemu.

Odpowiedź 1: OK [1XXX]

<response>
<code>1000</code>
<result>OK</result>
<timestamp>1286356644</timestamp>
<clTRID>a44B</clTRID>
<svTRID>1286356644.0246.21616</svTRID>
<command>domain-create</command>
<data>
<num>1311000863</num>
<expiration>2011-10-06</expiration>
</data>
<test>1</test>
</response>

To jest odpowiedź, gdy wszystko jest w porządku, a akcja została pomyślnie wykonana.

WAPI zawsze zwraca odpowiedź XML zawierającą pozycje coderesulttimestampsvTRID command. Może jednak nastać sytuacja, że niektóre z tych pozycji nie będą mogły być umieszczone w odpowiedzi (na przykład przy nieprawidłowym formacie zapytania). Elementy code i result znajdują się w odpowiedzi w każdych okolicznościach.

Jeśli w zapytaniu były parametry  clTRID, lub test, będą też zawarte w odpowiedzi. Element data jest umieszczany tylko w przypadku, gdy konieczne jest zwrócenie jakichś danych.

code

Element code zawiera zwracaną wartość polecenia. System kodów powrotu i ich lista znajduje się na stronie WAPI – wykaz kodów powrotu.

result

Opis tekstowy kodu powrotu.

timestamp

Czas wykonania polecenia w formacie UNIX.

clTRID

Identyfikator zapytania od klienta.

svTRID

Identyfikator zapytania po stronie serwera.

command

Polecenie WAPI.

data

W przypadku, że polecenie zwróci jakiekolwiek wartości, są one zapisane w tym elemencie. Dokładny opis zwracanych wartości jest opisany dla każdego polecenia.

Jeśli polecenie nie powiedzie się (tj. kod powrotu inny niż 1000), parametr data nie zostanie wstawiony.

test

Flaga trybu testowego.

Wstawiany w odpowiedzi na zapytania, które również zawierają tę flagę.

Odpowiedź 2: Błąd [XXXX]

<response>
<code>4050</code>
<result>Command not exists</result>
<timestamp>1286543689</timestamp>
<clTRID>E8bQ</clTRID>
<svTRID>1286543689.2416.28124</svTRID>
<command>omain-transfer-check</command>
</response>

Przykład prezentuje odpowiedź w przypadku błędu (nieznane polecenie).