Informacje ogólne

Żądanie/ request

Ponieważ serwisy API oparte są na architekturze REST, zatem wysyłane żądania są zwykłymi requestami HTTP.

Wymagane parametry requestu HTTP:

 

  • HTTP_METHOD: GET (wszystkie publiczne serwisy służą do pobierania danych)

 

  • ACCEPT: application/json
    Ewentualnie: application/json;CHARSET, np. application/json;charset=ISO-8859-2. Gdy charset nie ustawiony, wtedy domyślnie odpowiedź kodowana w UTF-8.
    API SAOS nie wspiera innych formatów odpowiedzi, np. xml.

 

Struktura odpowiedzi

  • Content-Type: application/json; charset=UTF-8 (wartość charset zależna od żądanego kodowania znaków w nagłówku Accept, patrz opis żądania)

 

Odpowiedź poprawna

Odpowiedź poprawna składa się z następujących sekcji:

  • links - zawiera odnośniki do podserwisów wchodzących w skład danego modułu API, odnośniki do kolejnych stron listy wyników itd.
  • items [dla listy wyników] - dane kolejnych elementów na liście wyników, np. dane pobranych orzeczeń
  • data [dla jednego żądanego elementu] - dane pobranego elementu, np. dane wybranego orzeczenia
  • queryTemplate - zawiera informacje na temat możliwych i dozwolonych parametrów żądania dla danego serwisu (samoopisujące się API)
  • info - dodatkowe zbiorcze informacje dot. wyników zapytania, np. liczba wszystkich orzeczeń w bazie spełniających kryterium żądania

 

Przykład:

{ 
  "links": [
     {"rel": "self","href": "https://www.saos.org.pl/api/dump/judgments?pageSize=20&pageNumber=0"},
     {"rel": "next","href": "https://www.saos.org.pl/api/dump/judgments?pageSize=20&pageNumber=1"}
 ],

  "items": [
    {"id": 76452,"courtType": "SUPREME","courtCases": ...},
    ...
 ],

 "queryTemplate": 
   {"pageSize": {"value": 20,"description": "Represents maximum number...","allowedValues": "Any integer greater..."},
     "sortingField": ["DATABASE_ID","JUDGMENT_DATE","CASE_NUMBER"],
   },

 "info" : {
    "totalResults" : 178765
  }
}


 

Błąd

W sytuacji, gdy żądanie nie może być poprawnie przetworzone, wtedy do klienta wysyłana jest odpowiedź zawierająca informację o błędzie. Informacja taka składa się z następujących punktów:

  • httpStatus - kod błędu http (taki sam wysyłany jest w nagłówku http)
  • reason - powód błędu
  • propertyName - nazwa atrybutu/parametru powodującego błąd
  • message - dłuższe tekstowe wyjaśnienie błędu

 

Przykład:

{
"error": {
    "httpStatus": "400", 
    "reason": "WRONG REQUEST PARAMETER", 
    "propertyName": "pageSiz", 
    "message": "parameter 'pageSiz' :  name is incorrect" }
}

 

Główny punkt wejścia

Żądanie/ Request

Opis

Główny punkt (korzeń drzewa) dostępnych serwisów. Publikuje listę odnośników do serwisów niższego poziomu: