Jak korzystać z API?

Od wersji 8.0 iDir oferuje ujednolicone API za pomocą którego można stworzyć automatyczne dodawarki, sprawdzarki albo panele moderacji centralnej. Niniejszy post jest krótkim wprowadzeniem do korzystania z API. Do testowania poszczególnych requestów polecam zaopatrzyć się w darmowy program Postman.

# Import dostępnych enpointów

Mając zainstalowany program Postman, w górnym menu należy wybrać Import, zaznaczyć zakładkę Link i wstawić link z oficjalnej dokumentacji API iDir https://demo.idir.intelekt.net.pl/docs/collection.json.

# Dodawanie nowych wpisów

Domyślnie w iDir dodawanie nowych wpisów dostępne jest zarówno dla zalogowanych użytkowników serwisu jak i gości. W przypadku dodawania wpisów jako gość, wymagane jest dodatkowo podanie unikalnego adresu email. Z racji tego API nie wymaga w tym przypadku autentykacji za pomocą tokena API.

Aby dodać wpis do katalogu należy znać ID grupy. Grupy można wyciągnąć za pomocą endpointu:

W naszym przykładzie interesujący nas ID grupy to 4.

W zależności od tego czy grupa jest płatna, potrzebujemy również ID ceny którą wybieramy. Ceny są relacją dla grupy więc w tym samym response poniżej ID grupy znajdziemy:

W naszym przykładzie interesuje nas cena ID 2, code_transfer za 10.00 PLN.

Dane powyższej ceny umożliwiają zakup tego kodu u operatora płatności, zakładam jednak, że katalogując duże ilości stron użytkownicy dodawarek będą mieć zakupione u administratorów katalogów specjalne tajne kody.

Grupy darmowe (pozbawione cen) nie wymagają podawania powyższych informacji, ani dokonywania jakichkolwiek płatności. Przy dodawaniu wpisu trzeba jednak wówczas podać captchę. Sposób pozyskania g-recaptcha-response z najczęściej stosowanej recaptchy pozostawiam już w gestii programisty implementującego API.

Niektóre grupy pozwalają (a czasem wręcz wymagają) na dodanie do wpisu dodatkowych pól jak np. nazwa firmy, adres itd. Pola te są również relacją dla grupy więc w tym samym response poniżej cen znajdziemy:

W naszym przykładzie interesują nas pola ulica (ID 3) i miasto (ID 4). Oba są obowiązkowe.

Ostatnim elementem potrzebnym do dodania wpisu są ID kategorii do których dodajemy wpis. Kategorie znajdziemy z użyciem filtra search za pomocą endpointu:

W naszym przykładzie interesuje nas kategoria o ID 119.

Mając te wszystkie informacje możemy dodać swój wpis. Robimy to za pomocą poniższego endpointu, ID grupy należy podać w zakładce Params, pozostałe dane w zakładce Body:

Wpis został dodany. W zależności od ustawienia grupy, wpis oczekuje na moderację, jest natychmiast aktywny lub (w przypadku ceny typu transfer lub paypal) oczekuje na płatność (adres do dokonania płatności znajdziemy korzystając z endpointu w zakładce Payments, wpisując odpowiednie UUID z powyższego response).

# Sprawdzanie wpisów

Automatyczne dodawarki przed próbą dodania wpisu wg powyższej instrukcji mogą najpierw sprawdzić czy dany wpis nie istnieje już w bazie, dodatkowo pobierając niektóre informacje jak aktualny status albo grupa w której wpis się znajduje.

Z racji tego, że są to dane wrażliwe (nie chcemy przecież, żeby dowolna osoba mogła sobie sprawdzać co chce w naszej bazie) endpoint do sprawdzania wpisów wymaga autoryzacji.

Załóżmy więc, że ufamy użytkownikowi któremu chcemy przydzielić dostęp. Możemy tego dokonać w panelu administracyjnym > zakładka Użytkownicy > korzystając z filtrów znajdując tego użytkownika i nadając mu rolę api w oknie edycji. Taki użytkownik uzyskuje dostęp do możliwości generowania własnych tokenów API w swoim profilu:

Uwaga: proszę uważnie wybierać użytkowników którym nadaje się uprawnienia dostępu do API. Taki użytkownik otrzymuje dostęp do informacji wrażliwych każdego wpisu jak grupa albo czas trwania premium!

Mając aktualny token można się nim posłużyć w poniższym endpoincie. Token należy wstawić w zakładce Authorization wybierając typ Bearer Token.

# Wyłączenie możliwości dodawania wpisów przez API

Jeśli chcemy zablokować możliwość dodawania wpisów przez dodawarki należy:

1. Opublikować routy API poleceniem:
   

   php artisan vendor:publish --tag=idir.routes.api

2. W pliku routes/vendor/idir/api/dirs.php - znaleźć:
   

   Route::post('dirs/group/{group}', [DirController::class, 'store'])
       // ->middleware(['permission:api.dirs.create', 'ability:api.dirs.create'])
       ->where('group', '[0-9]+')
       ->name('dir.store');
   
   Route::group(['middleware' => 'auth:sanctum', 'permission:api.access'], function () {
       Route::match(['post', 'get'], 'dirs/index', [DirController::class, 'index'])

   przenieść route store do middleware auth:sanctum oraz odkomentować pozostałe middleware:
   

   Route::group(['middleware' => 'auth:sanctum', 'permission:api.access'], function () {
       Route::post('dirs/group/{group}', [DirController::class, 'store'])
           ->middleware(['permission:api.dirs.create', 'ability:api.dirs.create'])
           ->where('group', '[0-9]+')
           ->name('dir.store');
   
       Route::match(['post', 'get'], 'dirs/index', [DirController::class, 'index'])

Wówczas dostęp do dodawania przez API będą mieć wyłącznie zautentykowani użytkownicy z rolą api. Jeśli nikomu nie nadamy takiej roli, nikt nie będzie mógł dodać wpisu przez API.

Powyższa instrukcja to zaledwie wstęp do korzystania z możliwości API. Nie omówione zostały m.in. endpointy do edycji czy moderacji wpisów. Do ich korzystania wymagana jest podstawowa znajomość API REST.