Autoryzacja

Dokumentacja PDF - API REST v 1.0.21 - Dokumentacja REST

API systemu FreshMail zostało zrealizowane według wzorca REST. Komunikacja polega na wysłaniu żądania HTTP pod adres https://api.freshmail.com/rest/ i ewentualnym przesłaniu wymaganych danych. Odpowiedź jest zwracana w formacie JSON.

Uwierzytelnienie

Każde wysłane żądanie po API wymaga uwierzytelnienia. Uwierzytelnienie następuje poprzez wysłanie nagłówków HTTP o nazwach:

X-Rest-ApiKey zawiera unikalny klucz dostępu do API, każdy z klientów posiada swój unikalny klucz API.
subskrypcje → lista subskrypcyjna → opcje zaawansowane i API
X-Rest-ApiSign zawiera podpis żądania. Podpis jest generowany na podstawie parametrów wysyłanych w żądaniu oraz na podstawie ApiSecret.

Istnieją dwa schematy generowania X-Rest-ApiSign, oba zostały przedstawione poniżej:

1. Schemat oparty na URL-encoded query

wymagane jest dodanie nagłówka Content-Type w żądaniu http o wartości:

text/html lub application/xml lub application/json, np.:
Content-Type: application/json

wtedy można wygenerować X-Rest-ApiSign w oparciu o algorytm:

sha1( ApiKey + GET_data + POST_data + ApiSecret )

gdzie:

ApiKey 32 znakowy klucz API.
GET_data pełna ścieżka dostępu – np. /rest/ping, /rest/mail itp. Więcej szczegółów w sekcji „Ścieżka dostępu”.
POST_data dane POST umieszczone w żądaniu. Jeśli w żądaniu znajdują się tylko dane GET to wartość POST_data jest pusta. Wartości muszą być escapowane na potrzeby URL, np.: email=test%40test.pl&subject=test+emaila
ApiSecret 40 znaków, unikalny sekret dla każdego z klientów. W przypadku skompromitowania klucza należy bezzwłocznie wygenerować nowy.

2. Schemat oparty na JSON

wymagane jest dodanie nagłówka Content-Type w żądaniu http w postaci:

Content-Type: application/json

wtedy można wygenerować X-Rest-ApiSign w oparciu o algorytm:

sha1( ApiKey + GET_data + JSON_data + ApiSecret )

gdzie:

ApiKey 32 znakowy Api key.
GET_data pełna ścieżka dostępu – np. /rest/ping, /rest/mail itp. Więcej szczegółów w sekcji „Ścieżka dostępu”.
JSON_data dane w formacie JSON jakie są wysyłane w żądaniu. Jeśli w żądaniu znajdują się tylko dane GET to wartość JSON_data jest pusta. Przykładowa wartość JSON_data: {"subscriber":"test@test.pl"}
ApiSecret 40 znaków, unikalny sekret dla każdego z klientów. W przypadku skompromitowania klucza należy bezzwłocznie wygenerować nowy.

Odpowiedzi API

Odpowiedź na każde żądanie wysłane do API jest w formacie JSON, np.

{"status":"OK","data":[1,2,3]}

Jeśli zapytanie powiedzie się wtedy pod kluczem „status” będziemy mieli wartość 'OK'. Jeśli metoda ma zwrócić dane będą one pod kluczem „data”. Natomiast jeśli wystąpi błąd pod kluczem „status” będzie wartość „ERROR”, a pod kluczem „errors” znajdzie się opis błędów jakie wystąpiły wraz z kodami błędów.

W przypadku błędu kod HTTP zwracany w nagłówku jest adekwatny do zaistniałego błędu, czyli np. 404, 403 itp. W przypadku braku błędu kod HTTP to 200.

Obsługa błędów

W razie wystąpienia błędu status odpowiedzi jest równy „ERROR” natomiast pole „errors” zawiera opis słowny błędu oraz kod błędu, np.

                {"errors":[
                           {"message":"Brak tematu emaila",
                           "code": 1202}
                       ],
               "status":"ERROR"}

lub

               {"errors":[
                          {"message": "Błędny adres odbiorcy",
                            "code": 1201},
                          {"message": "Brak tematu emaila",
                            "code": 1202}
                         ],
                "status":"ERROR"}

 Ścieżka dostępu

Każda z akcji jaką można wykonać ma swoją osobną ścieżkę dostępu. Ścieżka zbudowana jest w następujący sposób:

/rest/[Controller]/[Action]/[param]/[param]/[param]

Controller nazwa kontrolera np. ping, mail, itp.
Action nazwa akcji w obrębie kontrolera.
param parametr, nie może zawierać znaku „/”, w większości przypadków dodatkowe parametry GET są zbędne. Jeśli są wymagane to ilość oraz ich format jest podany w opisie akcji.

Ogólne kody błędów

500 Błąd serwera (Internal Server Error).
1000 Brak autoryzacji.
1001 Nie znaleziono kontrolera / akcji.
1002 Nieobsługiwany protokół. Proszę skorzystać z protokołu https.
1003 Nieobsługiwany rodzaj żądania, np. wysłano GET, a oczekiwano POST.
1004 Brak uprawnień do wywołania danego kontrolera/akcji