Informacje ogólne
Zakres funkcjonalności
Usługa API umożliwia wykonywanie operacji na obsługiwanych zasobach poprzez żądania HTTP zgodnie z filozofią REST. Obsługiwane zasoby to:
- domeny pocztowe
- konta pocztowe
- aliasy pocztowe
- listy pocztowe
Zgodnie z założeniami REST dostępne operacje na zasobach są reprezentowane przez dedykowane metody HTTP:
- GET - odczyt zasobu lub kolekcji (listy) zasobów
- POST - stworzenie nowego zasobu
- PUT - aktualizacja (modyfikacja) zasobu
- DELETE - usunięcie zasobu
Uwaga! Nie wszystkie typy operacji są dozwolone w kontekście dowolnego zasobu / typu zasobu.
Adres usługi
Ogólna postać adresu do usługi API wygląda następująco:
<PROTOKOL>://<DOMENA_API>:<PORT_USLUGI>/<WERSJA_API>/<SCIEZKA_ZASOBU>?<PARAMETRY_ZAPYTANIA>
- <PROTOKOL> - usługa API działa zawsze z użyciem bezpiecznego połączenia SSL czyli jest dostępna wyłącznie przez https://
-
<DOMENA_API> - ogólny algorytm do wyliczania domeny, pod która działa usługa API wygląda następująco:
- określić adres panelu pocztowego (webmail) dla posiadanego pakietu hostingowego/vps. W typowym przypadku będzie to:
- poczta.<domena_uslugi> lub
- poczta<numer>.<domena_uslugi>.
- zastąpić słowo poczta na as, czyli otrzymamy as.<domena_uslugi> lub as<numer>.<domena_uslugi>.
- określić adres panelu pocztowego (webmail) dla posiadanego pakietu hostingowego/vps. W typowym przypadku będzie to:
- <PORT_USLUGI> - jeśli panele poczty/webas działają na porcie 8080 wówczas usługa API również będzie działać na tym porcie. W innych przypadkach działa na standardowym porcie dla https - 443 i można go pominąć w ostatecznym adresie.
- <WERSJA_API> - oznaczenie wersji usługi API w postaci v<NUMER_WERSJI>, aktualna wersja to v1
- <SCIEZKA_ZASOBU> - ścieżka do zasobu, którego dotyczy zapytanie API - szczegółowo opisane w osobnych rodziałach
- <PARAMETRY_ZAPYTANIA> - dodatkowe opcjonalne parametry zapytania, z reguły do wpływania na postać odpowiedzi
Przykładowe adresy usługi API
https://as27.kei.pl/v1/emails/demo.kei.pl/postmaster https://as27.kei.pl/v1/aliases/demo.kei.pl?page=1&sort=name https://as27.kei.pl:8080/v1/emails/demo.kei.pl/postmaster
- <PROTOKOL>://<DOMENA_API> lub
- <PROTOKOL>://<DOMENA_API>:<PORT_USLUGI> (w przypadku działania na porcie 8080)
{ "service":{ "name":"Mail_Rest_Api", "version":"v1" } }
Wersje usługi
Odpytanie usługi API wymaga podania jej wersji. Aktualnie udostępniana usługa API ma numer: v1.
Format oraz kodowanie parametrów
Komunikacja z usługą API powinna odbywać się z użyciem kodowania unicode: UTF-8. Atrybuty dodawanych/modyfikowanych zasobów (żądania typu POST / PUT) powinny znajdować się w ciele żądania i być postaci:
- dokumentu JSON, klient powinien poinformować o tym usługę dodając nagłówek HTTP Content-Type: application/json
- zakodowanych parametrów url (URL Encoding)
Kody odpowiedzi
Zgodnie z filozofią REST informacja o sukcesie lub błędzie wykonania żądania API informuje kod HTTP w nagłówkach odpowiedzi. O sukcesie informuje kod z rodziny 2xx, w użyciu są:
- kod 200 - podstawowy kod sukcesu
- kod 201 - sukces po utworzeniu zasobu (dodawanie)
- kod 204 - sukces z pustym ciałem odpowiedzi (używane przez polecania DELETE, lub Multi-UPDATE )
Wystąpienie błędu jest oznaczane kodem z rodzin 4xx oraz 5xx. Kod odpowiedzi HTTP może ale nie musi jednoznacznie wskazywać na przyczynę problemu. W ciele odpowiedzi zawsze będą znajdować się dodatkowe informacje opisujące błąd - szczegółowiej opisane w osobnym rozdziale.
Przykłady nagłówków odpowiedzi sukcesu:
HTTP/1.1 200 OK Date: Wed, 26 Mar 2014 09:50:05 GMT Server: Apache Content-Length: 2007 Content-Type: application/json
HTTP/1.1 201 Created Date: Wed, 26 Mar 2014 09:55:08 GMT Server: Apache Location: /v1/emails/demo.kei.pl/nowe_konto Content-Length: 1251 Content-Type: application/json
HTTP/1.1 204 No Content Date: Wed, 26 Mar 2014 09:52:00 GMT Server: Apache Content-Length: 0 Content-Type: application/json
Przykłady nagłówków odpowiedzi z błędem:
HTTP/1.1 404 Not Found Date: Wed, 26 Mar 2014 09:54:41 GMT Server: Apache Content-Length: 224 Content-Type: application/json
HTTP/1.1 409 Conflict Date: Wed, 26 Mar 2014 09:58:58 GMT Server: Apache Content-Length: 223 Content-Type: application/json
HTTP/1.1 500 Internal Server Error Date: Wed, 26 Mar 2014 09:59:46 GMT Server: Apache Content-Length: 239 Connection: close Content-Type: application/json
Dodatkowe nagłówki
Zalecane jest dodawanie do każdego żądania do usługi API opcjonalnych nagłówków, które nie mają wpływu na przetwarzanie ale są logowane w historii operacji i mogą w przyszłości dostarczyć cennych informacji:
- X-User-IP: <ADRES_IP> - adres IP użytkownika końcowego, w przypadku gdy klient API pośredniczy między właścicielem zasobu (np posiadaczem konta pocztowego) a usługą API.
- User-Agent: <KLIENT_API> - nazwa klienta API (aplikacji), przydatne jeśli z usługi API korzysta kilka aplikacji