Przejdź do treści
dvnt.io

Automatyzacja i integracje16 min czytania3199 słówRedakcja dvnt

API — co to jest? REST API, webhook i OpenAPI wyjaśnione dla firmy

API co to jest: definicja na przykładach NBP, GUS i białej listy VAT, REST API, webhook, OpenAPI, klucze API i bezpieczeństwo integracji.

„Mamy do tego API” — to zdanie słyszy każdy, kto rozmawia z programistami albo z dostawcą oprogramowania. API co to jest? Najkrócej: API (application programming interface, interfejs programowania aplikacji) to ustalony sposób, w jaki jeden program prosi drugi o dane albo o wykonanie czynności — bez udziału człowieka, bez klikania w ekrany i bez przepisywania danych z jednego okna do drugiego.

Ten tekst jest dla właścicieli firm i menedżerów, którzy chcą rozumieć, o czym mówią ich programiści, na tyle dobrze, żeby zadać właściwe pytania. Zaczynamy od przykładów z życia polskiej firmy, potem przechodzimy do pojęć, które padają w każdej rozmowie o integracji: REST API, webhook, OpenAPI, klucz API. Każda definicja ma link do źródła, które ją ustanawia — dokumentacji, specyfikacji albo standardu.

API — co to jest, na przykładzie z życia firmy

Najłatwiej zrozumieć API na trzech usługach, z których korzysta wiele polskich firm, często nie wiedząc, że robi to przez API.

Kurs walut z NBP. Program księgowy, który sam wpisuje kurs euro z tabeli NBP do faktury walutowej, nie otwiera strony banku. Wysyła zapytanie do serwisu api.nbp.pl, który — jak opisuje go NBP — „udostępnia publiczne Web API umożliwiające klientom HTTP wykonywanie zapytań” na zbiorach danych o kursach walut i cenach złota, aktualnych i archiwalnych.

Dane firmy z GUS. Formularz, który po wpisaniu NIP sam uzupełnia nazwę i adres kontrahenta, zwykle pobiera je z rejestru REGON. GUS udostępnia go przez usługę BIR1 (Baza Internetowa REGON 1) — usługę sieciową, w której można wyszukiwać po numerze REGON, NIP albo KRS.

Biała lista VAT. Przed zapłatą większej faktury firma może automatycznie sprawdzić, czy kontrahent jest czynnym podatnikiem VAT i czy numer konta jest na wykazie. Ministerstwo Finansów udostępnia do tego API Rejestr WL — z zapytaniem o podatnika po NIP i o to, czy dany rachunek bankowy należy do danego NIP.

We wszystkich trzech przypadkach schemat jest ten sam: jeden program (klient) wysyła zapytanie w ustalonym formacie, drugi (serwer) odsyła odpowiedź, też w ustalonym formacie. API to właśnie ta umowa — jakie zapytania można wysłać, jakich danych potrzebują i co wróci w odpowiedzi.

Tak wygląda to w praktyce. Poniżej zapytanie o bieżący średni kurs euro, wykonane 30 września 2026 roku według wzorów zapytań opublikowanych na api.nbp.pl, i odpowiedź serwera w formacie JSON:

GET https://api.nbp.pl/api/exchangerates/rates/a/eur/?format=json
{"table":"A","currency":"euro","code":"EUR","rates":[{"no":"190/A/NBP/2026","effectiveDate":"2026-09-30","mid":4.3672}]}

Nie trzeba umieć programować, żeby to przeczytać: tabela A, waluta euro, numer tabeli, data i kurs średni 4,3672 zł. Program księgowy robi dokładnie to samo, tylko sam wstawia liczbę we właściwe pole.

REST API — co to jest i skąd się wzięło

Kiedy programista mówi „mamy REST API”, ma na myśli API zbudowane według określonego stylu architektury. Termin REST (Representational State Transfer) wprowadził Roy Fielding w rozprawie doktorskiej z 2000 roku. W rozdziale 5 wyprowadza go krok po kroku, dokładając kolejne ograniczenia do systemu, który na początku nie ma żadnych.

Sześć ograniczeń REST według Fieldinga

  1. Klient–serwer. Klient (aplikacja, która prosi o dane) i serwer (system, który je przechowuje) są rozdzielone i mogą rozwijać się niezależnie.
  2. Bezstanowość. Każde zapytanie musi być zrozumiałe samo w sobie. Fielding pisze: „each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server” — „każde zapytanie od klienta do serwera musi zawierać wszystkie informacje potrzebne do jego zrozumienia i nie może korzystać z kontekstu przechowywanego na serwerze” (tłumaczenie własne). Dlatego w każdym zapytaniu do API wysyła się na przykład klucz — serwer „nie pamięta”, kto pytał minutę wcześniej.
  3. Pamięć podręczna (cache). Odpowiedzi mogą być oznaczone jako takie, które wolno zapamiętać i użyć ponownie, co oszczędza zapytania.
  4. Jednolity interfejs. To serce REST. Fielding: „REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state” — „REST definiują cztery ograniczenia interfejsu: identyfikacja zasobów, operowanie na zasobach przez ich reprezentacje, samoopisujące się komunikaty oraz hipermedia jako mechanizm stanu aplikacji” (tłumaczenie własne). W praktyce: każdy zasób (faktura, przesyłka, link) ma swój adres, a operacje na nim wykonuje się tymi samymi, standardowymi metodami.
  5. System warstwowy. Między klientem a serwerem mogą stać pośrednicy — na przykład serwery pamięci podręcznej czy zabezpieczenia — a klient nie musi o nich wiedzieć.
  6. Kod na żądanie. Serwer może wysłać klientowi kod do wykonania. To jedyne ograniczenie opcjonalne — Fielding pisze, że zmniejsza przejrzystość systemu, „and thus is only an optional constraint within REST” („dlatego jest w REST tylko ograniczeniem opcjonalnym”, tłumaczenie własne).

RESTful API — co to znaczy

„RESTful API” to po prostu API, które stosuje się do tych zasad. W codziennym użyciu oba określenia — REST API i RESTful API — znaczą to samo: API dostępne przez HTTP, w którym zasoby mają adresy, a operacje wykonuje się standardowymi metodami HTTP. Wiele API nazywanych REST-owymi nie spełnia wszystkich sześciu warunków co do joty, szczególnie tego o hipermediach. Dla firmy, która z nich korzysta, nie ma to zwykle znaczenia — liczy się, czy API jest dobrze opisane i przewidywalne.

Metody HTTP i idempotentność

W REST API to metoda HTTP mówi serwerowi, co ma zrobić z zasobem. Znaczenie metod ustala standard HTTP, dziś w wersji RFC 9110:

  • GET — pobierz: „requests transfer of a current selected representation for the target resource” (żąda przesłania bieżącej reprezentacji zasobu);
  • POST — przetwórz dane wysłane w zapytaniu według zasad danego zasobu; w praktyce najczęściej: utwórz nowy rekord;
  • PUT — utwórz albo zastąp zasób stanem wysłanym w zapytaniu;
  • DELETE — usuń powiązanie między zasobem a jego dotychczasową funkcją, czyli w praktyce: usuń.

Dla biznesu najważniejsze jest jedno pojęcie z tego standardu: idempotentność. RFC 9110 definiuje ją tak: metoda jest idempotentna, „if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request” — „jeśli zamierzony skutek wielu identycznych zapytań tą metodą jest dla serwera taki sam jak skutek jednego takiego zapytania” (tłumaczenie własne). Idempotentne są PUT, DELETE i metody bezpieczne, czyli tylko odczytujące — w tym GET. POST idempotentny nie jest.

Dlaczego to ważne? Bo połączenia się zrywają. Standard wyjaśnia, że zapytanie idempotentne można automatycznie ponowić, gdy komunikacja przerwie się, zanim klient odczyta odpowiedź. Dwa razy wysłane „usuń fakturę nr 15” da ten sam wynik co jedno. Dwa razy wysłane „utwórz płatność” może dać dwie płatności. Dlatego integracje płatności wymagają osobnej ochrony przed duplikatami — w naszym kalkulatorze kosztu aplikacji webowej opis tej pozycji mówi wprost, że integracja płatności „wymaga obsługi webhooków, logiki idempotentności i testów compliance — to nie tylko osadzenie widżetu checkout”.

Schemat idempotentności według RFC 9110, dwa przebiegi obok siebie.
Połączenie zerwane, zapytanie ponowione — co dostaje serwerSchemat idempotentności według RFC 9110, dwa przebiegi obok siebie. Górny: zapytanie DELETE „usuń fakturę nr 15” zostaje wysłane, połączenie zrywa się, zanim klient odczyta odpowiedź, więc zapytanie jest automatycznie ponawiane; skutek po dwóch zapytaniach jest taki sam jak po jednym — faktura usunięta raz. Tak samo zachowują się GET i PUT. Dolny: zapytanie POST „utwórz płatność” wysłane, połączenie zerwane, zapytanie ponowione; serwer tworzy dwie płatności, bo POST nie jest idempotentny. Dlatego integracja płatności potrzebuje osobnej ochrony przed duplikatami. Schemat bez wartości liczbowych.Źródło: dvnt, schemat własny

API SOAP a REST

Starsze systemy — bankowe, administracyjne, korporacyjne — często udostępniają API w innym standardzie: SOAP. Według specyfikacji W3C SOAP 1.2 (rekomendacja z 27 kwietnia 2007 roku) to „a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment” — „lekki protokół przeznaczony do wymiany ustrukturyzowanych informacji w zdecentralizowanym, rozproszonym środowisku” (tłumaczenie własne), oparty na technologiach XML.

Różnica z perspektywy firmy jest praktyczna, nie ideologiczna. SOAP to protokół z własną, ściśle określoną kopertą komunikatu w XML. REST to styl architektury, który korzysta z tego, co HTTP już daje: adresów, metod i kodów odpowiedzi, a dane przesyła zwykle w JSON. Jeśli dostawca udostępnia tylko SOAP, integracja jest jak najbardziej możliwa — wymaga po prostu innych narzędzi i zwykle więcej pracy przy obsłudze komunikatów. Nie podajemy tu statystyk, który standard jest „popularniejszy”, bo nie znaleźliśmy takich, za którymi dałoby się stanąć.

Webhook — co to jest i czym różni się od zapytania do API

Zwykłe API działa na zasadzie „zapytaj, a dostaniesz odpowiedź”. Jeśli chcesz wiedzieć, czy klient zapłacił, musisz co jakiś czas pytać. Webhook odwraca ten kierunek: to system, u którego coś się wydarzyło, sam wysyła wiadomość na wskazany przez ciebie adres.

GitHub opisuje to w swojej dokumentacji webhooków najprościej, jak się da: webhooki pozwalają „receive data as it happens, as opposed to polling an API (calling an API intermittently) to see if data is available” — „otrzymywać dane w chwili, gdy się pojawiają, zamiast odpytywać API (wywoływać je co jakiś czas), żeby sprawdzić, czy dane są dostępne” (tłumaczenie własne). Stripe, operator płatności, pisze, że po zarejestrowaniu adresu odbiorczego „Stripe pushes real-time data to it when events happen in your Stripe account” — wysyła na niego dane w czasie rzeczywistym, gdy na koncie coś się dzieje, w formacie JSON przez HTTPS.

Dwie osie czasu obok siebie.
Zapytanie do API a webhookDwie osie czasu obok siebie. Górna, odpytywanie API (pull): twój system co pewien czas wysyła zapytanie „czy są nowe dane?”; kolejne odpowiedzi brzmią „nie”, „nie”, „tak — oto dane”; zdarzenie, które nastąpiło między zapytaniami, zostaje zauważone dopiero przy następnym zapytaniu. Dolna, webhook (push): zdarzenie u dostawcy, na przykład opłacona płatność, i w tej samej chwili dostawca wysyła wiadomość na adres twojego systemu; twój system szybko odpowiada kodem 2xx i dopiero potem przetwarza dane. Schemat bez wartości liczbowych.Źródło: Opracowanie własne na podstawie dokumentacji webhooków GitHub i Stripe, odczyt 30.09.2026

W praktyce oba podejścia się uzupełniają. Webhook jest lepszy, gdy liczy się czas reakcji — płatność, nowe zamówienie, zmiana statusu przesyłki. Odpytywanie wystarcza, gdy dane zmieniają się rzadko albo gdy dostawca webhooków po prostu nie oferuje. Stripe daje odbiorcom jedną ważną radę: adres odbierający webhooki powinien szybko zwrócić kod sukcesu (2xx), zanim zacznie wykonywać jakąkolwiek złożoną logikę, która mogłaby spowodować przekroczenie czasu oczekiwania.

Podpis webhooka: skąd wiadomo, że wiadomość jest prawdziwa

Adres, na który przychodzą webhooki, jest publiczny — każdy może wysłać na niego cokolwiek, na przykład fałszywą informację „zamówienie opłacone”. Dlatego poważni dostawcy podpisują każdą wiadomość, a odbiorca musi ten podpis sprawdzić.

  • Stripe umieszcza podpis w nagłówku Stripe-Signature i generuje go jako HMAC z funkcją SHA-256, używając sekretu przypisanego do danego adresu odbiorczego. Podpisywany jest znacznik czasu razem z treścią wiadomości. Znacznik czasu chroni przed ponownym wysłaniem przechwyconej, starej wiadomości: biblioteki Stripe mają domyślną tolerancję 5 minut między znacznikiem a bieżącym czasem (Stripe, webhooks).
  • GitHub wysyła podpis w nagłówku X-Hub-Signature-256, zawsze z przedrostkiem sha256=. Dokumentacja ostrzega, żeby nie porównywać podpisów zwykłym operatorem ==, tylko funkcją porównującą „w stałym czasie” — takim porównaniem nie da się odgadywać podpisu po czasie odpowiedzi (GitHub, weryfikacja dostarczeń).

HMAC to podpis tworzony wspólnym sekretem: zna go tylko nadawca i odbiorca, więc tylko oni mogą wygenerować i sprawdzić poprawny podpis. Dla właściciela firmy wniosek jest prosty: pytając dostawcę integracji o webhooki, zapytaj też, czy wiadomości są podpisane i czy twój system ten podpis sprawdza.

OpenAPI — co to jest i po co firmie dokumentacja API

API bez dokumentacji jest jak umowa, której nikt nie spisał. OpenAPI to standard, w którym tę umowę się zapisuje. Aktualna wersja specyfikacji to OpenAPI Specification 3.2.1, opublikowana 10 września 2026 roku. Jej pierwsze zdanie mówi, czemu służy: „The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic” — „Specyfikacja OpenAPI (OAS) definiuje standardowy, niezależny od języka programowania opis interfejsu dla API działających przez HTTP, który pozwala zarówno ludziom, jak i komputerom poznać i zrozumieć możliwości usługi bez dostępu do kodu źródłowego, dodatkowej dokumentacji czy podglądania ruchu sieciowego” (tłumaczenie własne).

W praktyce plik OpenAPI wymienia wszystkie adresy API, metody, wymagane pola, możliwe odpowiedzi i sposób uwierzytelniania. Z takiego pliku narzędzia same generują czytelną dokumentację w przeglądarce, z której programista może od razu wysłać próbne zapytanie.

Po co to firmie, a nie tylko programistom?

  • Wymiana wykonawcy nie zaczyna się od zera. Jeśli API twojego systemu jest opisane w OpenAPI, nowy zespół wie, co ono robi, bez czytania całego kodu.
  • Partnerzy integrują się sami. Zamiast tłumaczyć każdemu kontrahentowi przez e-mail, jak wysłać zamówienie, dajesz mu link do dokumentacji.
  • Łatwiej sprawdzić, co zostało zrobione. Specyfikacja jest konkretnym produktem, który można odebrać razem z aplikacją.

Dlatego w naszym kalkulatorze pozycja „publiczne API / integracje” obejmuje, jak mówi jej opis, „klucze API, rate limiting i dokumentację OpenAPI” — nie tylko sam kod.

API key i bezpieczeństwo integracji

Klucz API, token Bearer i limity zapytań

API key (klucz API) to długi, losowy ciąg znaków, który identyfikuje program wysyłający zapytania i daje mu dostęp. Najczęściej przekazuje się go w nagłówku Authorization jako tzw. token Bearer — „okaziciela”: kto go ma, ten ma dostęp. Z tego wynikają trzy zasady praktyczne. Klucz trzyma się wyłącznie na serwerze, nigdy w kodzie strony widocznym w przeglądarce ani w wiadomości e-mail. Każda integracja powinna mieć osobny klucz, żeby w razie wycieku dało się unieważnić jeden, a nie wszystkie. Klucze warto okresowo wymieniać.

Część dostawców zamiast stałego klucza stosuje standard OAuth, w którym aplikacja dostaje token w imieniu konkretnego konta — tak jest w API Allegro i InPost opisanych niżej.

Drugi element to limity zapytań (rate limiting). Dostawca ogranicza, ile zapytań można wysłać w danym czasie, żeby jeden klient nie przeciążył usługi. Dobrze zaprojektowane API mówi o tym w odpowiedzi — na przykład nagłówkami z limitem, liczbą pozostałych zapytań i czasem odnowienia. Twoja integracja musi te limity szanować: rozkładać zapytania w czasie i nie ponawiać ich w kółko po odmowie.

OWASP API Security Top 10 2023

Organizacja OWASP, która zajmuje się bezpieczeństwem aplikacji, publikuje osobną listę dziesięciu najważniejszych zagrożeń dla API. Wersja z 2023 roku wygląda tak (tytuły w oryginale, objaśnienia nasze):

  1. API1:2023 – Broken Object Level Authorization — API nie sprawdza, czy pytający ma prawo do konkretnego rekordu; zmiana numeru faktury w adresie pokazuje cudzą fakturę.
  2. API2:2023 – Broken Authentication — wadliwe logowanie i obsługa kluczy lub tokenów.
  3. API3:2023 – Broken Object Property Level Authorization — brak kontroli nad pojedynczymi polami: API zwraca albo pozwala zmienić pola, do których użytkownik nie powinien mieć dostępu.
  4. API4:2023 – Unrestricted Resource Consumption — brak limitów zapytań i zasobów, co grozi przeciążeniem albo wysokimi rachunkami.
  5. API5:2023 – Broken Function Level Authorization — zwykły użytkownik może wywołać funkcje przeznaczone dla administratora.
  6. API6:2023 – Unrestricted Access to Sensitive Business Flows — procesy biznesowe (zakup, rezerwacja, rejestracja) można hurtowo automatyzować ze szkodą dla firmy.
  7. API7:2023 – Server Side Request Forgery — API pobiera zasób spod adresu podanego przez użytkownika i daje się nakłonić do zapytań w miejsca, do których nie powinno sięgać.
  8. API8:2023 – Security Misconfiguration — błędy konfiguracji: zbędne funkcje włączone, brak aktualizacji, zbyt szczegółowe komunikaty o błędach.
  9. API9:2023 – Improper Inventory Management — firma nie wie, jakie wersje i adresy API ma wystawione; stare, zapomniane wersje zostają otwarte.
  10. API10:2023 – Unsafe Consumption of APIs — nadmierne zaufanie do danych z cudzych API, bez ich sprawdzania.

Ostatni punkt dotyczy każdej firmy, która tylko korzysta z cudzych API: dane z zewnątrz też trzeba sprawdzać. Jak podzielona jest odpowiedzialność za bezpieczeństwo, gdy dane leżą u zewnętrznego dostawcy, opisujemy w tekście o bezpieczeństwie danych w chmurze.

API, z którymi pracuje polska firma

Większość integracji w polskiej firmie dotyczy kilku tych samych usług. Poniżej zestawienie z odnośnikami do oficjalnej dokumentacji.

Mapa sześciu publicznych API pogrupowanych według obszaru.
API, z których korzysta polska firmaMapa sześciu publicznych API pogrupowanych według obszaru. Podatki i finanse: KSeF API 2.0 Ministerstwa Finansów (faktury ustrukturyzowane, środowiska TEST, DEMO i PROD), API Rejestr WL — biała lista VAT (wersja 1.6.0), NBP Web API (kursy walut i ceny złota, jedno zapytanie obejmuje maksymalnie 93 dni). Dane o firmach: GUS BIR1 — rejestr REGON (bezpłatne, wymaga klucza użytkownika, wersje 1.1 i 1.2). Sprzedaż i logistyka: Allegro REST API (token OAuth), InPost ShipX (OAuth 2.0).Źródło: Oficjalna dokumentacja: Ministerstwo Finansów, NBP, GUS, Allegro, InPost, odczyt 30.09.2026
  • KSeF API 2.0 — Krajowy System e-Faktur to według Ministerstwa Finansów „centralny system teleinformatyczny służący do wystawiania i pobierania faktur ustrukturyzowanych w postaci elektronicznej”. Przewodnik dla integratorów jest na github.com/CIRFMF/ksef-api; ministerstwo udostępnia środowiska testowe, demonstracyjne i produkcyjne oraz własne biblioteki w C# i Javie. Informacje dla integratorów: ksef.podatki.gov.pl.
  • Allegro REST API — Allegro udostępnia funkcje platformy przez API „w oparciu o architekturę REST”, z metodami GET, POST, PUT, PATCH i DELETE; każde zapytanie wymaga tokena OAuth w nagłówku Authorization, jest też środowisko testowe (developer.allegro.pl).
  • InPost ShipX — API, które według InPost „integruje całość naszych usług, tj. przesyłki kurierskie, paczkomatowe jak również e-commerce”, z autoryzacją w standardzie OAuth 2.0 (dokumentacja ShipX). Zastrzeżenie: ta strona dokumentacji była ostatnio edytowana w listopadzie 2022 roku, więc przed integracją warto zapytać InPost o aktualny portal.
  • GUS BIR1 — dane z rejestru REGON; GUS podaje, że „usługa i dane udostępniane są bezpłatnie”, ale do środowiska produkcyjnego potrzebny jest klucz użytkownika, o który prosi się e-mailem. Dostępne są wersje 1.1 i 1.2, ta druga od grudnia 2024 (api.stat.gov.pl).
  • NBP Web API — kursy walut i ceny złota, zapytania metodą GET, odpowiedź w JSON (domyślnie) lub XML; pojedyncze zapytanie może obejmować najwyżej 93 dni, a od 1 sierpnia 2025 serwis działa tylko przez HTTPS (api.nbp.pl). Strona NBP nie opisuje rejestracji ani klucza — ale też nie mówi wprost, że klucz nie jest potrzebny.
  • API białej listy VAT — API Rejestr WL Ministerstwa Finansów, wersja 1.6.0, z zapytaniami o podatnika po NIP i o przypisanie rachunku do NIP (wl-api.mf.gov.pl).

Najuczciwszy przykład integracji, jaki możemy pokazać, to nasz własny. DVN Links to nasza polska platforma do skracania linków z analityką i kodami QR. Strona, którą czytasz, korzysta z jej publicznego REST API przy każdej publikacji artykułu lub strony — tego samego API, które dostają klienci planów płatnych (według cennika dostęp do API jest od planu Starter).

Co dokładnie robi nasza strona, w prostych słowach:

  1. Tworzy krótki link przy publikacji. Jeśli dokument nie ma jeszcze krótkiego linku, strona wysyła zapytanie POST /links z docelowym adresem i zapisuje w dokumencie krótki adres oraz identyfikator linku.
  2. Sprawdza link przy kolejnych publikacjach. Jeśli identyfikator już jest, strona pyta GET /links/{id}, czy link nadal istnieje i dokąd prowadzi.
  3. Odtwarza link, jeśli ktoś go usunął w panelu DVN Links — po prostu tworzy nowy.
  4. Aktualizuje cel przy zmianie adresu. Gdy zmienia się adres artykułu, strona wysyła PATCH /links/{id} z nowym adresem docelowym. Stary krótki link dalej działa i prowadzi już pod nowy adres.
  5. Przejmuje stare linki. Dokumenty, które miały krótki link zapisany sprzed tej integracji, ale bez identyfikatora, strona odnajduje przez wyszukiwanie po dokładnym adresie docelowym i przejmuje znaleziony link, zamiast tworzyć duplikat.

Dwie decyzje projektowe są tu ważniejsze od samych zapytań. Po pierwsze, integracja nigdy nie blokuje zapisu — jeśli DVN Links nie odpowie, artykuł i tak się opublikuje, a błąd trafi tylko do logów. Po drugie, bez skonfigurowanego klucza API integracja po prostu nic nie robi. Widać tu też w praktyce różnicę z sekcji o idempotentności: POST tworzy nowy zasób, więc przed nim strona zawsze sprawdza, czy link już istnieje.

Schemat decyzji integracji z API DVN Links przy publikacji artykułu lub strony.
Co robi nasza strona z API DVN Links przy każdej publikacjiSchemat decyzji integracji z API DVN Links przy publikacji artykułu lub strony. Jeśli w dokumencie nie ma identyfikatora krótkiego linku, strona najpierw szuka linku po dokładnym adresie docelowym; znaleziony przejmuje, a jeśli go nie ma, tworzy nowy zapytaniem POST /links i zapisuje krótki adres oraz identyfikator. Jeśli identyfikator jest, strona pyta GET /links/[id], czy link istnieje: gdy ktoś go usunął, tworzy nowy; gdy adres artykułu się zmienił, wysyła PATCH /links/[id] z nowym celem, a stary krótki link prowadzi już pod nowy adres. Dwie zasady: integracja nigdy nie blokuje zapisu — błąd trafia do logów, a artykuł się publikuje; bez klucza API integracja nic nie robi. DVN Links nie ma webhooków, więc to odpytywanie w chwili publikacji. Schemat bez wartości liczbowych.Źródło: dvnt, schemat własny

Samo API DVN Links ma cechy, o które warto pytać każdego dostawcę. Jest opisane specyfikacją OpenAPI 3.1.0, z której generowana jest dokumentacja w przeglądarce. Wszystkie zapytania wymagają klucza przekazywanego jako token Bearer w nagłówku Authorization. Limity zapytań zależą od planu, a każda odpowiedź niesie nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.

DVN Links nie ma webhooków. Dlatego to przykład odpytywania: nasza strona sama sprawdza stan linku, kiedy go potrzebuje, zamiast czekać na powiadomienie. Przy tym zastosowaniu to wystarcza, bo link sprawdzamy tylko w chwili publikacji.

Integracja API zamiast przepisywania danych — kiedy się opłaca

Każda integracja przez API zastępuje pracę, którą ktoś w firmie wykonuje ręcznie: przepisuje zamówienia z platformy do systemu magazynowego, kopiuje kurs walut do faktury, sprawdza kontrahenta na białej liście przed przelewem. Pytanie nie brzmi „czy integrować”, tylko „które przepisywanie kosztuje nas najwięcej”.

Integracja przez API zwykle ma sens, gdy:

  • ta sama czynność powtarza się często — codziennie albo przy każdym zamówieniu, a nie raz na kwartał;
  • pomyłka jest kosztowna — błędny numer konta, zła kwota na fakturze, niewysłana przesyłka;
  • liczy się czas reakcji — klient czeka na potwierdzenie płatności albo numer przesyłki;
  • obie strony mają udokumentowane API — najlepiej w OpenAPI albo przynajmniej z pełną dokumentacją i środowiskiem testowym.

Integracja nie ma sensu, gdy czynność zdarza się rzadko, a dostawca nie ma API albo zmienia je bez uprzedzenia. Wtedy utrzymanie integracji kosztuje więcej niż ręczna praca.

Koszt samej integracji zależy od jej zakresu. Dla orientacji: w naszym kalkulatorze kosztu aplikacji webowej pozycja „publiczne API / integracje” to +8 000 zł netto, a integracja płatności online +5 000 zł netto — do ceny aplikacji, która zaczyna się od Lean MVP od 10 tys. zł i MVP od 30 tys. zł. To punkt wyjścia, nie cennik: każdą integrację wyceniamy indywidualnie, bo zależy od jakości API po drugiej stronie.

Gdy integracji jest kilka i zaczynają się łączyć w proces — zamówienie, faktura w KSeF, etykieta przesyłki, powiadomienie klienta — to już automatyzacja procesu, a nie pojedyncze połączenie. Piszemy o tym w tekście o automatyzacji procesów biznesowych, a nasze podejście opisuje oferta automatyzacji procesów. Jeśli integracje mają być częścią nowego systemu, zacznij od tekstu o tym, czym jest aplikacja webowa, i od naszej oferty tworzenia aplikacji webowych. Kiedy gotowe narzędzia z integracjami nie wystarczają, zostaje dedykowane oprogramowanie. Pozostałe teksty o aplikacjach webowych zebraliśmy w przewodniku po aplikacjach webowych.

Najczęstsze pytania o API

API — co to jest w prostych słowach?

API to ustalony sposób, w jaki jeden program prosi drugi o dane albo o wykonanie czynności, bez udziału człowieka. Przykład: program księgowy sam pobiera kurs euro z serwisu api.nbp.pl, a formularz sam uzupełnia dane kontrahenta z rejestru REGON przez usługę GUS BIR1. API określa, jakie zapytania można wysłać, jakich danych wymagają i co wróci w odpowiedzi.

REST API — co to jest?

REST API to API zbudowane według stylu architektury REST, który opisał Roy Fielding w rozprawie doktorskiej z 2000 roku. Każdy zasób, na przykład faktura czy przesyłka, ma swój adres, a operacje wykonuje się standardowymi metodami HTTP: GET pobiera, POST tworzy, PUT zastępuje, DELETE usuwa. Każde zapytanie zawiera wszystkie informacje potrzebne do jego zrozumienia, bo serwer nie przechowuje kontekstu poprzednich zapytań.

Webhook — co to jest?

Webhook to wiadomość, którą system dostawcy sam wysyła na adres twojego systemu, gdy coś się wydarzy — na przykład gdy płatność zostanie opłacona. Zwykłe API trzeba odpytywać co jakiś czas, a webhook przychodzi w chwili zdarzenia. Adres odbierający webhooki jest publiczny, dlatego dostawcy tacy jak Stripe czy GitHub podpisują wiadomości kodem HMAC SHA-256, a odbiorca powinien ten podpis sprawdzać.

API key — co to jest?

Klucz API to długi, losowy ciąg znaków, który identyfikuje program wysyłający zapytania i daje mu dostęp do API. Zwykle przekazuje się go w nagłówku Authorization jako token Bearer, więc kto ma klucz, ten ma dostęp. Klucz trzyma się wyłącznie na serwerze, każda integracja powinna mieć osobny klucz, a klucze warto okresowo wymieniać.

Czy integracja przez API jest bezpieczna?

Może być, jeśli spełnia kilka warunków: klucze są przechowywane tylko na serwerze, API sprawdza uprawnienia do każdego rekordu i ma limity zapytań, webhooki są podpisane i weryfikowane, a dane z cudzych API są sprawdzane przed użyciem. Listę najczęstszych błędów zawiera OWASP API Security Top 10 2023 — to dobry punkt wyjścia do rozmowy z wykonawcą integracji.

Powiązane artykuły