10 cech dobrego API, które sprawią, że integracja API będzie przyjemna
Wdrożenie API bez bólu — jak zintegrować API w systemach firmy i na co zwrócić uwagę, żeby rozpoznać czy API zostało dla nas dobrze przygotowane. Integracja API nie musi być trudna!
Odkąd rosnące oczekiwania biznesowe i coraz to nowe wymagania regulacyjne, napędzają rosnącą liczbę integracji API w biznesie, wiele wewnętrznych działów technicznych różnorakiej wielkości firm staje przed zadaniem wdrożenia Interfejsów Programowania Aplikacji w swoich systemach.
Wdrożenie API (inaczej integracja z API), któresłuży wówczas jako łącznik wewnętrznych baz danych i CRM’ów z siecią dostawców danych i partnerów, może być z zasady dwojakie — przyjemne jak ciepły letni deszcz, albo męczące niczym spędzona na materacu z cierni noc.
I tak jak w życiu, tak i podczas integracji API, jeśli coś nie idzie, tak jak powinno, to albo Ty coś robisz źle wdrażając API, albo wina leży po drugiej stronie i API zostało źle przygotowane. Ciężka integracja z API to nie zawsze wina Klienta — czasem zawinia software house czy dostawca danych.
Trudna integracja z API — Jak poznać, kto popełnił błąd?
Dwie różne osoby potrafią tak opisać tę samą sytuację, że nasuwa się wątpliwość, czy to istotnie ta sama sytuacja.
Korzystając z naszego doświadczenia, wynikającego z wystawiania API dla biznesu (API KRS+CEIDG, API AML, aplikacje zasilające firmy w informacje gospodarcze itp.), w niniejszym artykule dzielimy się wiedzą, jak poznać czy API zostało dobrze wystawione czy nie.
Pool or trigger — jak rozpocząć integrację API?
Zanim przejdziemy do szczegółów dobrze przygotowanego API REST, istotna jest jedna kwestia — określenie w jaki sposób chcemy uruchomić API. Dostaliśmy już od dostawcy API dane do uwierzytelnienia i autoryzacji koniecznej do uruchomienia usługi, i teraz czas na nas.
W celu sprawdzenia przesyłu danych po API, stosuje się zasadniczo jedną z dwóch metod:
- rozpoczynamy aktywne pobieranie danych (tzw. polling), czyli odpytujemy API o konkretne dane, będąc całkowicie odpowiedzialnymi za ilość pobieranych danych i kontrolę tego procesu,
- ustawiamy tzw. Webhook trigger, czyli zamiast odpytywać aplikację o konkretne dane, “prosimy” API, by poinformowało nas o zmianach w bazie danych.
Pierwsza metoda jest łatwiejsza i świetnie dzięki niej przyjrzymy się temu, jak API wygląda, ale i posiada jedną sporą wadę. Nie jesteśmy w stanie sprawdzić, czy API działa w czasie rzeczywistym. Po prostu pobieramy stopniowo bazę danych. Integracja API zrobiona, teraz testujemy.
Druga metoda, przynajmniej od strony implementacyjnej, znacznie trudniejsza, pozwala nam zweryfikować działanie API real-time. Wysyłamy request po zadanej strukturze zgodnie z dostępnymi metodami i obserwujemy jak API reaguje. Tym niemniej i ona ma wady. Mianowicie, nie jesteśmy w stanie kontrolować ilości przesyłanych do nas danych oraz musimy wystawić serwer na zewnątrz, a w większych firmach stanowi to już znaczny problem z uwagi na przyjęte wewnętrznie procedury.
Dobrze przygotowane API da się sprawdzić obiema metodami. Polling pokaże nam jaka jest jakość API, a webhooki sprawdzą aktualność i reakcje aplikacji.
10 cech dobrze przygotowanego API
1:. Możliwość wyszukania po kryteriach / dacie
Dobrze przygotowane API koniecznie musi dawać możliwość wyszukiwania danych po określonych kryteriach.
W zależności od specyfiki API, mogą one być różnorakie.
Np. w naszych podstawowych real-time API KRS-CEIDG, które służą weryfikacji firm, podstawowymi kryteriami wyszukania danych w interfejsie API są identyfikatory podmiotów gospodarczych — numery NIP, KRS, REGON, PESEL, nazwa. Charakterystyka tego API polega bowiem na tym, że użytkownik posiada jakieś dane podmiotu gospodarczego i to, czego oczekuje, to aktualne dane rejestrowe, pozwalające sprawdzić potencjalnego kontrahenta.
Gdyby jednak interesowało go API z bazami firm, gdzie potrzebowałby analizować firmy, które np. powstały w 2019 roku, kluczowym kryterium byłaby data (możliwość zaznaczenia zakresu daty rejestracji od 1.01.2019 do np. 30.07.2019).
2:. Stronicowanie wyników API
Stronicowanie wyników (z ang. paging) stanowi nieodłączny element funkcjonalnego API, bo opcja ograniczenia ilości danych, które możemy pobrać za jednym razem, określenie częstotliwości requestów oraz powiadomienia ile stron danych nam jeszcze zostało do pobrania, pozwalają na efektywne zarządzanie dużymi zbiorami danych.
Dzięki stronicowaniu jesteśmy w stanie ustalić, że np. dziś chcemy pobrać jedynie 3 strony danych, bo tyle nam wystarczy.
3:. Requesty, które rzeczywiście odpowiadają potrzebom
Każde wywołanie API powinno mieć swój własny Use Case — obsługiwać konkretny przypadek użycia, który zostaje spełniony przy tym pojedynczym żądaniu. Nie chodzi bowiem o to, by API było tak podzielone na małe części, że trzeba korzystać z więcej niż jednego requestu, by uzyskać dane, które standardowo są nam potrzebne.
4:. Sortowanie danych
Ta cecha nie jest obligatoryjna w każdym API, bo zależy od jego rodzaju. W wielu przypadkach Interfejsów Programowania Aplikacji wystarczą nam świetnie zaprojektowanie requesty (patrz punkt wyżej!).
Dla przykładu, nie ma potrzeby sortowania danych przy API KRS. Podobnie przy API pogodowym. Bo co tam sortować?
Ale jeżeli nasze API służy np. pobraniu 100 milionów e-booków, to sortowanie będzie już nam niezbędne. Jeśli nie możemy posortować danych, czyli ich uporządkować (np. po znaczniku czasu, tytule, autorze), stronicowanie pamięci będzie nieskuteczne, bo nie pozwoli nam określić, które dane już pobraliśmy, a które nie i w jakiej kolejności chcemy je pobrać.
5:. JSON / REST
API oczywiście nie musi być REST, żeby uznane zostało za dobrze przygotowane, tym niemniej obecnie praktycznie wszyscy klienci oczekują wystawienia dla nich łatwiejszego w implementacji REST. Krótko mówiąc, SOAP powoli odchodzi do lamusa.
REST domyślnie obsługuje format JSON, a ten z kolei jest powszechnie nr 1 wśród istniejących formatów.
Dlaczego JSON?
Oczywiście REST API obsługuje poza JSON’em również TXT, CSV czy XML (tu wskazujemy tylko najpopularniejsze), jednak JSON nadal pozostaje globalnie najbardziej uniwersalnym formatem — jest lżejszy niż XML, zajmuje mniej miejsca i parsowanie danych jest z niego najłatwiejsze.
6:. Szybkość API
Api jest fajne jeżeli jest szybkie. Wszak każdy z nas, pytając o coś, otrzymać odpowiedź chce natychmiast, a nie po pięciu dniach.
Nie ma jednego standardu szybkości API, jednak bezsprzecznie powinno ono sprawnie radzić sobie z zapytaniami i wspierać równoległe zapytania API (jeżeli chcemy zaimplementować API np. na 20 komputerach, to powinno sobie z tym poradzić, a nie tworzyć zatory w odpowiedziach).
7:. Środowisko testowe / tryb testowy API
Środowisko testowe tudzież tryb testowy, czyli taka wersja API, która ma ograniczoną ilość wywołań, ale pozwala nam spokojnie przetestować API i realne dane, jakie ono dostarcza, bez naliczania jakichkolwiek opłat jeszcze przed integracją, to również wielce poszukiwana cecha API.
Tłumaczyć tego jakoś szczególnie nie trzeba. Miłoby byłoby np. pograć sobie na giełdzie w środowisku testowym, a nie na realnych pieniądzach, gdzie każde eksperymentalne kliknięcie powoduje odejmowanie pieniędzy z naszego konta.
8:. Jasne komunikaty błędów
Często niedoceniane komunikaty błędów, przydają się w monitorowaniu API i zarządzaniu zmianami. Z jednej strony pozwalają na walidację danych wejściowych od użytkownika, a z drugiej strony umożliwiają zapisywanie brakujących i niepełnych danych i późniejszą ich optymalizację.
9:. Autoryzacja z OAuth
Czytany jako zabawny oh-autch, otwarty standard autoryzujący (OAuth) pomaga udostępniać dane API podmiotom trzecim. Ten bezpieczny sposób delegowania dostępów do zasobów serwera definiowany jest podczas autoryzacji i zwyczajowo wymaga użycia tokenów.
Innymi słowy, każdy kto otrzymuje token, może zyskać dostęp do danych z serwera.
W przeciwieństwie do przyznawania dostępu na przykład za pomocą klucza API, autoryzacja OAuth jest znacznie znacznie bardziej skomplikowana przy implementacji, ale i znacznie podnosi bezpieczeństwo.
10:. Rzetelnie przygotowana dokumentacja techniczna
Brzmi jak banał, ale banałem nie jest. Nadal multum dokumentacji technicznych pisanych jest na kolanie “dla siebie”, a nie dla zewnętrznego użytkownika, który przecież nie zna jeszcze tego konkretnego API.
A dobra dokumentacja techniczna — jasno opisana i solidnie porządkująca całość API — jest niczym instrukcja obsługi z IKEA. Z nią zaoszczędzimy mnóstwo czasu.
Więcej o tym zagadnieniu pisaliśmy przy okazji oddzielnego artykułu Jak napisać dobrą dokumentację techniczną?
10 jeźdźców dobrego API czy więcej?
Powyższa lista 10-ciu cech dobrego API nie jest listą skończoną. Gdybyśmy zapytali tysiąc programistów, jakie są cechy dobrego API, z pewnością otrzymalibyśmy sporo duplikatów, ale i tyle samo (jak nie więcej!) unikalnych odpowiedzi.
Każdy zwraca uwagę na coś innego. Coś innego jest ważne. Inne oczekiwania ma się wobec API X, a inne wobec API Y.
Dla przykładu, zastanawialiśmy się przez chwilę, czy nie powinniśmy dodać jeszcze cechy dobrego API nr 11 — bibliotek.
Wszak to niezwykle wygodne dostać od razu od dostawcy API biblioteki do różnych języków programowania. Poświęca się wówczas mniej czasu na integrację i ma się pewność, że wykorzystujemy API dokładnie tak, jak zakładał to jego autor.
Tylko, że przygotowanie bibliotek trwa, a czas to pieniądz i większość klientów nie chce dodatkowo płacić za biblioteki. W rzeczywistości biblioteki przygotowują tylko gigantyczne firmy, które naprawdę stać na tygodnie pracy nad bibliotekami albo firmy, które mają jedno pudełkowe API w tysiącach egzemplarzy i ilość klientów uzasadnia koszt.
Mogą zainteresować Cię również:
