API

Do opisu udostępnianych API zdecydowaliśmy się użyć standardu Swagger. Jest to zdobywający popularność język i zestaw narzędzi służących do dokumentacji API, dosŧępu do nich przez graficzny interfejs, jak i generowania klientów w wielu językach.

Swagger-spec w wersji 2.0 dostępny jest pod adresem https://api-v3.mojepanstwo.pl/swagger.json. Propozycje zmian w API przyjmujemy jako pull-requesty ze zmianami w tym pliku (do edycji zalecamy użycie Swagger Editor).

Dla ułatwienia przeglądania API prezentujemy je za pomocą przeglądarki Swagger-UI na stronie głównej.

API Dane oferuje mechanizm wyszukiwania z filtrowaniem pełnotekstowym oraz po konkretnych polach, stronicowaniem oraz sortowaniem.

Wszystkie parametry wyszukiwania podaje się w części query zapytania (po ?). Parametry tablicowe podaje się zgodnie z konwencją wykorzystywaną przez CakePHP i Rails:

• Lista elementów - ?layers[]=dataset&layers[]=details
• Tablica asocjacyjna - ?conditions[imie]=Jan&conditions[nazwisko]=Kowalski
• Pojedyczny element tablicy - skrót w postaci ?layers=dataset

Podczas wyszukiwania w cześci query można użyć następujących pól:

• conditions - Filtry ograniczające zbiór danych, można filtrować po wszystkich polach zwracanych w tablicy data wybranego obiektu, np. ?conditions[imie]=Jan&conditions[nazwisko]=Kowalski
• q - Pełnotekstowe wyszukiwanie (z odmianą) po podstawowych polach, np. ?q=epanstwo
• order - Sortowanie w formacie "pole (desc|asc)", np. ?order=nazwisko asc
• page - Numer strony wyników do zwrócenia. Strony numerowane są od 1. Domyślna ilosć wyników na stronie to 50. Przykład: ?page=2
• limit - Ilość wyników zwróconych na stronie (domyślnie 50)

Każdy zasób udostępniany przez serwer jest jednoznacznie identyfikowany poprzez unikalny adres URL (pole url). Taki URL zapewnia także łatwą (potencjalnie automatyczną) nawigację między zasobami.

Przykładowo: {"url": "https://api-v3.mojepanstwo.pl/dane/poslowie/1"}

Aby ułatwić linkowanie do naszego serwisu udostępniamy także dla obiektów link, pod którym wysŧępuje on w serwisie mojePaństwo.

Przykładowo: {"mp_url": "https://mojepanstwo.pl/dane/poslowie/1"}

Chcąc zapewnić lekką reprezentację obiektów w API i jednocześnie ułatwić dostęp do szczegółów i powiązań z innymi obiektami wprowadziliśmy mechanizm warstw. Warstwy pozwalają na wydzielenie dodatkowych informacji o obiekcie i zostawienie decyzji klientowi API, czy chce te warstwy od razu otrzymać, czy doładować później. Ładowanie warstw jest dostępne wyłącznie podczas zwracania pojedynczego obiektu.

Listę dostępnych warstw jest wyświetlana w ramach obiektu:

	GET: https://api-v3.mojepanstwo.pl/dane/kody_pocztowe/1
	
	{
	    "id": "864053",
	    "dataset": "kody_pocztowe",
	    "object_id": 17003,
	    "data": {
	        "gminy_str": "Warszawa",
	        "id": "17003",
	        "kod": "00-511",
	        "kod_int": "511",
	        "liczba_gmin": 1,
	        "liczba_miejsc": 2,
	        "liczba_miejscowosci": 1,
	        "liczba_powiatow": 1,
	        "miejscowosci_str": "Warszawa",
	        "wojewodztwo_id": "7"
	    },
	    "score": {
	        "name": "score",
	        "value": 1,
	        "boost": false
	    },
	    "layers": {
	        "obszary": null,
	        "gminy": null,
	        "miejsca": null,
	        "miejscowosci": null,
	        "powiaty": null,
	        "struktura": null,
	        "dataset": null
	    }
	}
	

Warstwy ładuje sie poprzez podanie w zapytaniu nazw warstw jako tablicy: https://api-v3.mojepanstwo.pl/dane/kody_pocztowe/1?layers[]=obszary&layers[]=gminy

Istnieje także skrót pozwalający załadować wszystkie warstwy na raz: https://api-v3.mojepanstwo.pl/dane/kody_pocztowe/1?layers=*

API do obsługi błędów wykorzystuje standardowe i mniej standardowe kody HTTP:

• 400 Bad Request - Błędne żądanie (źle sformatowane wejście, brakujące wymagane parametry)
• 401 Unauthorized - Zasób jest dostępny, ale tylko po autentykacji klienta. Należy przejść proces autentykacji.
• 404 Not Found - Nie znaleziono zasobu. Podano niepoprawną ścieżkę.
• 418 I'm a teapot - Wykonanie żądania zakończyła się oczekiwanym błędem. Błąd zwracany jest w postaci:

  	{“code”: ERROR_CODE_DICTIONARY_ENTRY, // kod błędu, opisany na konkretnym API
  	 “params”: { // tablica - parametry błędu (niezależne od języka, specyficzne dla danego kodu błędu)}
  	    "param1": "value1",
  	 },
  	 "error_description": "Długi opis w domyślnym języku, jeżeli Http Accept Language nie został podany, lub jest nieobsługiwany"
  	}

• 422 Unprocessable Entity - Błędy wprowadzanych danych w postaci:

  	{"errors": {
  	    "fld1": ["validation_err1", "validation_err2", ...],
  	    ...
  	    }
  	}

API wersjonujemy liczbami całkowitymi poczynając od 1. Zmiana wersji API wiąże się z utraceniem kompatybilności wstecznej. Może to wiązać się z usunięciem pewnych pól/metod, zmianą znaczenia istniejących lub zmianą istotnych mechanizmów API (sortowania, filtrowania, paginacji, autentykacji).

Kolejne wersja API udostępniane są pod adresami o formacie https://api-v%duza_wersja%.mojepanstwo.pl/. Starsze wersje API będą wyłączane po okresie przejściowym, nie krótszym niż 6 miesięcy. Obecna wersja API to V3.

Zachęcamy użytkowników do zarejestrowania się w serwisie. Pozwoli to nam informować o wprowadzanych zmianach w działaniu serwisu. Będziemy ogłaszać mailowo zarówno wprowadzanie nowych wersji API aplikacji, jak i stopniowe wycofywanie wersji starszych. Docelowo wprowadzimy obowiązkową rejestrację w serwisie.