Buduj aplikacje w oparciu o dane publiczne
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:
?layers[]=dataset&layers[]=details
?conditions[imie]=Jan&conditions[nazwisko]=Kowalski
?layers=dataset
Podczas wyszukiwania w cześci query można użyć następujących pól:
data
wybranego obiektu, np. ?conditions[imie]=Jan&conditions[nazwisko]=Kowalski
?q=epanstwo
?order=nazwisko
asc
?page=2
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.