Czym jest API? Przewodnik po prostu dla twórców aplikacji

API (interfejs programistyczny aplikacji) to zdefiniowany sposób, w jaki jedno oprogramowanie prosi drugie o dane albo o wykonanie czegoś. Twoja aplikacja wysyła żądanie w uzgodnionym formacie — „podaj jutrzejsze rezerwacje”, „obciąż tę kartę kwotą 20 €”, „streść ten tekst” — a drugi system odsyła ustrukturyzowaną odpowiedź. API to sposób, w jaki części aplikacji rozmawiają ze sobą, i jak Twoja aplikacja korzysta z zewnętrznych usług, takich jak płatności, e-mail, mapy czy AI.

Dlaczego API mają znaczenie przy budowaniu z AI

Prawie każda przydatna aplikacja składa się z części, które komunikują się przez API:

• Wewnątrz aplikacji ekrany w przeglądarce wywołują API Twojego własnego backendu, by wczytać i zapisać dane.
• Na zewnątrz aplikacji Twój backend wywołuje API innych firm: Stripe do przyjmowania płatności, dostawca e-maili do wysyłania paragonów, dostawca modeli AI do generowania tekstu.

Kiedy prosisz kreatora AI, by „przyjmował płatności” albo „dodał podsumowanie AI”, on w rzeczywistości pisze kod, który wywołuje API. Znajomość podstaw pomaga zrozumieć, czego AI od Ciebie potrzebuje (zwykle konta w danej usłudze i klucza API), gdzie coś może się zepsuć i ile to będzie kosztować.

Codzienna analogia

Wyobraź sobie restaurację. Nie wchodzisz do kuchni i nie gotujesz. Czytasz menu, mówisz kelnerowi, czego chcesz, w sposób, który kuchnia rozumie, a kelner przynosi Ci jedzenie — albo mówi, że danie się skończyło.

• Menu to dokumentacja API: lista tego, o co możesz poprosić i jak.
• Kelner to API: jeden uzgodniony sposób, w jaki zamówienia wchodzą, a odpowiedzi wychodzą.
• Kuchnia to drugi system: nie musisz wiedzieć, jak działa w środku.
• Twoje zamówienie to żądanie; talerz to odpowiedź.

Kuchnia może zmienić piece i personel, nie wpływając na Ciebie, dopóki menu pozostaje takie samo. W tym tkwi prawdziwa wartość API: pozwala dwóm systemom współpracować, bez konieczności znania przez żaden z nich wnętrza drugiego.

Jak działa żądanie do webowego API

Najczęściej spotkasz webowe API działające przez HTTP, czyli ten sam protokół, z którego korzysta przeglądarka. Każde żądanie ma kilka części:

A każda odpowiedź ma:

JSON (JavaScript Object Notation) to prosty format tekstowy z nazwami i wartościami w nawiasach klamrowych. To standardowy sposób, w jaki webowe API wymieniają dane.

REST: najpopularniejszy styl

REST to powszechnie stosowana konwencja projektowania webowych API. Każdy rodzaj obiektu dostaje własny URL, a standardowe metody mówią, co się z nim robi. Oto jak mogłoby wyglądać REST API dla aplikacji rezerwacji:

PUT też istnieje i zgodnie z konwencją zastępuje cały rekord, podczas gdy PATCH zmienia tylko wysłane pola.

Kody statusu, które zobaczysz najczęściej:

Kiedy Twoja aplikacja się psuje, kod statusu jest często najszybszą wskazówką. Błąd 401 od dostawcy płatności zwykle oznacza brakujący lub błędny klucz API; 429 oznacza, że wywołujesz API zbyt często.

REST to nie jedyny styl — istnieją też GraphQL i API w stylu RPC — ale to REST najczęściej stosują usługi i backendy budowane przez AI.

Przykład: potwierdzenie rezerwacji

Kiedy klient rezerwuje strzyżenie w aplikacji salonu, w ciągu sekundy lub dwóch może dojść do kilku wywołań API:

1. Strona rezerwacji w przeglądarce wysyła POST /api/bookings z usługą, godziną i danymi klienta do Twojego backendu.
2. Backend sprawdza, czy termin jest wolny, zapisuje rezerwację w bazie danych i zwraca 201 Created.
3. Backend wywołuje API dostawcy e-maili kluczem sekretnym: „wyślij to potwierdzenie na lena@example.com”.
4. Jeśli jest zaliczka, Twój backend prosi API dostawcy płatności o utworzenie sesji checkout i wysyła tam klienta.
5. Później dostawca płatności wywołuje Twoją aplikację, by powiadomić, że płatność się powiodła. To odwrotne wywołanie to webhook.

Pierwsze dwa kroki to Twoje własne API między frontendem a backendem. Kroki 3–5 to API zewnętrznych dostawców.

Wyjaśnienie najważniejszych pojęć

Częste błędy i mylne przekonania

• Umieszczanie tajnych kluczy w frontendzie. Wszystko, co jest w kodzie uruchamianym w przeglądarce, może zobaczyć każdy, kto odwiedzi stronę. Tajne klucze muszą zostać na serwerze, w zmiennych środowiskowych lub sekretach.
• Wklejanie kluczy do czatu. Historia czatu może być przechowywana. Zamiast tego użyj funkcji sekretów kreatora, a każdy klucz, który wyciekł, wymień.
• Zakładanie, że API jest darmowe. Wiele API pobiera opłaty za żądanie lub za jednostkę zużycia — API modeli AI liczy się w tokenach. Sprawdź cennik i ustaw limity wydatków. Zobacz jak używać API LLM.
• Brak obsługi błędów. Zewnętrzne usługi padają, przekraczają czas i trafiają na limity. Poproś o sensowne komunikaty błędów i ponawianie prób.
• Ufanie przeglądarce. Twoje własne API musi samo sprawdzać uprawnienia. Ukrycie przycisku nie powstrzyma kogoś, kto wywoła endpoint bezpośrednio.
• Używanie kluczy produkcyjnych podczas testów. Używaj kluczy trybu testowego, dopóki nie będziesz gotowy na start.

O co poprosić swojego kreatora AI

• „Z których zewnętrznych API korzysta ta aplikacja i ile kosztuje każde z nich?”
• „Wywołuj API płatności tylko z serwera. Odczytuj klucz ze zmiennej środowiskowej.”
• „Wypisz każdy endpoint naszego API, co robi i kto może go wywołać.”
• „Sprawdź po stronie serwera, czy zalogowany użytkownik jest właścicielem rezerwacji, zanim ją zaktualizujesz lub usuniesz.”
• „Jeśli API e-maili zawiedzie, zapisz rezerwację mimo to i zaloguj błąd.”
• „Na razie używaj trybu testowego dostawcy.”

API w Mythex

Mythex może zbudować Twoje własne API — jako część aplikacji webowej albo jako osobny backend w Node, Pythonie (FastAPI), C# lub Javie, działający obok frontendu — i napisać kod wywołujący usługi zewnętrzne. Klucze dodajesz jako sekrety projektu, a nie w czacie, i są dostępne dla aplikacji w podglądzie oraz po publikacji. Dokumentacja zawiera przepisy na integrację dowolnego API i backend REST API.

Pytania