Przykłady użycia

Dostęp do serwisu za pośrednictwem REST API może być trudny dla osób, które nie miały z tych wcześniej styczności. Z tego powodu, poniżej zamieszczone zostały podstawowe przykłady wykorzystania API w celu pobrania udostępnionych danych. Poniższy opis pokrywa jedynie niewielki fragment funkcjonalności serwisu. Jeżeli interesuje Cię pełna dokumentacja techniczna, kliknij tutaj. Interfejs graficzny dokumentacji pozwala na opytywanie API bez potrzeby programowania lub ręcznego wykonywania zapytań do API serwisu.

1. Rejestracja i logowanie

1.1. Rejestracja nowego konta

Pierwszym krokiem, który powinniśmy zrobić jest stworzenie konta i zalogowanie się. Dostępne są dwa sposoby rejestracji:

Rejestracja przy pomocy graficznego interfejsu serwisu. Naciśnij przycisk Zarejestruj się w ekranie głównym (lub kliknij: tutaj).
Rejestracja przy pomocy REST API serwisu (zobacz endpoint /api/v1/users/register/ w dokumentacji API).

Do rejestracji wymagany jest: email użytkownika, jego imię i nazwisko oraz hasło. Zalecanym i znacznie prostrzym sposobem rejestracji jest użycie interfejsu. Jeżeli konto nie zostało aktywowane, to nie będzie można się nim zalogować.

1.2. Logowanie w serwisie

Logowanie umożliwia dostęp do danych przy pomocy serwisu. W celu uzyskania dostępnu do API wymagane jest uzyskanie odpowiednich tokenów autoryzacyjnych. Sposób uzyskania tokenów został opisany w kolejnej sekcji tego dokumentu.

W celu zalogowania stworzonego wcześniej konta naciśnij przycisk Zaloguj się w ekranie głównym (lub kliknij: tutaj).

2. Autoryzacja

2.1. Uzyskanie tokenów

Dostęp do api autoryzowany jest przy pomocy standardu JWT (JSON Web Token, zob: https://en.wikipedia.org/wiki/JSON_Web_Token). Podejście to zakłada użycie dwóch typów tokenów:

Token access - używany w celu autoryzacji do API,
Token refresh - używany w celu odświeżenia tokenu access.

W celach zapewnienia bezpieczeństwa, długość życia tokenów została ograrniczona:

Token access aktywny jest 60 minut,
Token refresh aktywny jest 1 dzień.

Zaczymany od wykonania zapytania typu POST do endpointu /api/v1/token/. Uzyskanie tokenów przypomina proces logowania. W treści zapytania przesyłamy login i hasło użytkownika.

                      
curl 'http://fajne-dane.herokuapp.com/api/v1/token/' \
  -H 'Content-Type: application/json' \
  --data-raw '{"email":"EMAIL UŻYTKOWNIKA","password":"HASŁO"}'

W odpowiedzi od systemu otrzymujemy object JSON zawierający dwa tokeny: access oraz refresh:

                      
{
    "refresh": "4ZDcxNThjM2Q4YSIsInVzZXJfaWQiOjF9.AqXKTaB63CH6DCMI6Qqf90LnKKjyT6Vi8vyVWbIiWBc[...]",
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxN[...]"
}

2.2. Odświeżenie tokenu `access`

Zaczymany od wykonania zapytania typu POST do endpointu /api/v1/token/refresh. W treści zapytania przesyłamy jedynie nasz aktywny refresh token. Jeżeli używany token wygasł (minęło ponad 24 godziny), to wymagane jest ponowne użycie endpointu /api/v1/token/ w celu uzyskania nowej pary tokenów.

                      
curl 'http://fajne-dane.herokuapp.com/api/v1/token/refresh/' \
  -H 'Content-Type: application/json' \
  --data-raw '{"refresh":"4ZDcxNThjM2Q4YSIsInVzZXJfaWQiOjF9.AqXKTaB63CH6DCMI6Qqf90LnKKjyT6Vi8vyVWbIiWBc[...]"}'

W odpowiedzi od systemu otrzymujemy object JSON zawierający dwa tokeny: access oraz refresh:

                      
{
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxN[...]"
}

3. Zbiory danych

3.1. Dostęp do zbiorów danych

Wszystkie zbiory danych dostępne są w dwóch formach:

Dane surowe, w których oprócz finalnych oznaczeń dokumentu dostępne są również odrzucone odpowiedzi.
Dane zaagregowane, które mają postać prostych do pobrania plików CSV i zawierają jedynie zaakceptowane oznaczenia dokumentów.

Najprostrzym sposobem dostepu do danych jest pobranie danych zaagregowanych przy pomocy serwisu. Aby zobaczyć listę wszystkich dostępnych zbiórów danych w raz z linkami do plików, wystarczy nacisnąć: tutaj

Innym sposobem jest dostęp do plików przy pomocy API. Aby pobrać listę wszystkich dostępnych zbiorów danych wystarczy użyć endpointu /api/v1/reports/sources/. Dostęp do API wymaga przekazania tokenu autoryzacyjnego access w nagłówku zapytania:

                      
curl 'http://fajne-dane.herokuapp.com/api/v1/reports/sources/' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiw[...]' \

W odpowiedzi otrzymamy listę wszystkich dostępnych zbiorów danych, wraz z linkami do plików CSV, które można pobrać.

                      
[
  {
    "id": 1,
    "campaign_name": "NAZWA ZBIORU DANYCH",
    "file_url": "LINK DO PLIKU"
  },
  ...
]