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>.
    W przypadku specyficznej konfiguracji posiadanej usługi w celu ustalenia adresu usługi API należy skontaktować się z biurem obsługi klienta.
  • <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
Aby zweryfikować poprawność adresu, należy sprawdzić czy po otwarciu adresu uzyskanego przez wyrażenie
  • <PROTOKOL>://<DOMENA_API> lub
  • <PROTOKOL>://<DOMENA_API>:<PORT_USLUGI> (w przypadku działania na porcie 8080)
np. https://as27.kei.pl uzyskujemy treść postaci:
{
  "service":{
    "name":"Mail_Rest_Api",
    "version":"v1"
  }
}
Uwaga! Usługa API pozwala na połączenia tylko od klienta działającego na tym samym adresie IP co ona (wywołania wewnątrz vps). Jeśli jest zapotrzebowanie na połączenie z innych adresów IP należy ten fakt zgłosić do biura obsługi klienta.

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