REST - co to jest? Definicja pojęcia KSeF
Co to jest REST?
REST (Representational State Transfer) to sposób projektowania interfejsów programistycznych (API), który wykorzystuje standardowe metody protokołu HTTP do komunikacji między systemami. REST jest jednym z najpopularniejszych sposobów budowania API.
W kontekście KSeF API 2.0, REST oznacza, że komunikacja z systemem odbywa się przez standardowe żądania HTTP: GET - do pobierania danych (np. pobranie faktury), POST - do wysyłania danych (np. wysłanie faktury), PUT - do aktualizacji danych, DELETE - do usuwania danych (np. cofnięcie uprawnienia).
Każda operacja w KSeF API ma swój adres (endpoint), np. POST /api/v2/sessions/online/{referenceNumber}/invoices/ do wysłania faktury. REST jest prosty, standardowy i łatwy do zrozumienia dla programistów.
Jak działa REST w KSeF?
W KSeF API 2.0 komunikacja REST wygląda następująco: programista wysyła żądanie HTTP do odpowiedniego adresu (endpointu) z danymi w formacie JSON lub XML, system KSeF przetwarza żądanie i zwraca odpowiedź (sukces lub błąd) również w formacie JSON/XML, każda operacja ma swój unikalny adres i metodę HTTP. Przykłady: pobranie faktury - GET /api/v2/invoices/{invoiceNumber}, wysłanie faktury - POST /api/v2/sessions/online/{referenceNumber}/invoices/, sprawdzenie statusu - GET /api/v2/operations/{referenceNumber}.
Endpointy REST
Endpoint to adres URL, pod którym dostępna jest określona funkcjonalność API. W KSeF API 2.0 endpointy są zorganizowane logicznie: /api/v2/auth/* - uwierzytelnianie i autoryzacja, /api/v2/sessions/* - zarządzanie sesjami (interaktywne i wsadowe), /api/v2/invoices/* - operacje na fakturach, /api/v2/permissions/* - zarządzanie uprawnieniami, /api/v2/operations/* - sprawdzanie statusu operacji. Każdy endpoint wymaga odpowiedniej autoryzacji (token JWT) i zwraca dane w standardowym formacie.
Zalety REST
REST jest popularny, ponieważ: jest prosty i standardowy (wykorzystuje znany protokół HTTP), jest niezależny od języka programowania (można używać dowolnego języka), jest łatwy do debugowania (można testować żądania w przeglądarce lub narzędziach jak Postman), jest dobrze udokumentowany (standardowe formaty odpowiedzi), jest skalowalny (łatwo dodać nowe endpointy). KSeF API 2.0 wykorzystuje wszystkie zalety REST, co czyni integrację prostszą i bardziej przewidywalną.
FAQ
Czy REST to to samo co API?
Nie, to są różne pojęcia. API (Application Programming Interface) to ogólne określenie interfejsu programistycznego - sposobu komunikacji między systemami. REST to konkretna architektura (sposób projektowania) API, która wykorzystuje protokół HTTP. KSeF ma API, które jest zbudowane w architekturze REST.
Czy są alternatywy dla REST?
Tak, istnieją inne architektury API, np. SOAP (starsza, bardziej złożona), GraphQL (nowsza, bardziej elastyczna), gRPC (szybsza, ale bardziej złożona). KSeF API 2.0 używa głównie REST, choć w niektórych przypadkach może używać SOAP. REST jest wyborem KSeF, ponieważ jest prosty, standardowy i łatwy do zrozumienia.
Czy muszę rozumieć REST, żeby korzystać z KSeF?
Nie, jeśli korzystasz z Aplikacji Podatnika KSeF (portalu webowego) lub programu księgowego zintegrowanego z KSeF, nie musisz wiedzieć nic o REST - wszystko dzieje się automatycznie. Wiedza o REST jest potrzebna tylko programistom, którzy bezpośrednio integrują systemy z KSeF API.
Jak mogę testować REST API KSeF?
Możesz użyć narzędzi do testowania API, takich jak Postman, Insomnia lub curl (wiersz poleceń). KSeF udostępnia również interaktywną dokumentację OpenAPI (Swagger), gdzie możesz testować endpointy bezpośrednio w przeglądarce. Pamiętaj, że do testowania potrzebujesz środowiska testowego KSeF i odpowiednich danych uwierzytelniających.