Formularz pogodowy działa na stronie, ale dane o temperaturze trzeba skądś pobrać. Zwykle łączy się wtedy stronę z zewnętrzną usługą przez API, choć sposób komunikacji i dostęp do danych zależą od zasad ustalonych przez tę usługę.

API pozwala programom korzystać z ustalonych funkcji i danych
- API to interfejs, przez który program korzysta z funkcji lub danych innego programu.
- Web API często przyjmuje żądanie HTTP i zwraca odpowiedź, na przykład w formacie JSON.
- REST jest jednym z podejść do projektowania API, a nie synonimem każdego interfejsu.
- Klucz API może identyfikować aplikację, ale sam nie potwierdza, że konkretna osoba ma dostęp do danych.
API to umowa między programami, a nie osobny program
Wyobraź sobie okienko na dworcu: podajesz bilet i dostajesz informację, bez wchodzenia na zaplecze. API działa podobnie: określa, z jakich funkcji albo danych może skorzystać inny program i w jaki sposób ma o nie poprosić.
Skrót pochodzi od angielskiego Application Programming Interface, czyli interfejsu programowania aplikacji. Interfejs opisuje dostępne operacje, wymagane dane i możliwe odpowiedzi. Nie odsłania przy tym całego kodu ani sposobu działania usługi, z którą program się łączy. Takie rozumienie API obejmuje zarówno interfejsy internetowe, jak i te dostępne w przeglądarce lub systemie operacyjnym, co opisuje MDN Web Docs.
Żądanie i odpowiedź pokazują, jak działa web API
W aplikacji pogodowej strona wysyła prośbę o prognozę dla wybranego miasta. Serwer sprawdza żądanie, pobiera właściwe dane i odsyła odpowiedź, którą aplikacja może wyświetlić na ekranie. To wymiana komunikatów, nie bezpośrednie połączenie strony z bazą danych.
W web API takie żądanie zwykle biegnie przez HTTP. Może wskazywać konkretny adres, używać metody takiej jak GET albo POST i zawierać parametry lub dane. Odpowiedź może mieć postać JSON, czyli tekstu ułożonego w pary nazw i wartości:
{
"city": "Gdańsk",
"temperature": 18
}
Przykładowy kod JavaScript może pobrać dane z dostępnego adresu API:
const response = await fetch("/api/weather?city=Gdansk");
const data = await response.json();
console.log(data.temperature);
Adres w przykładzie jest umowny, a prawdziwe API może wymagać klucza, tokenu albo określonych parametrów. Format odpowiedzi i zasady dostępu zawsze sprawdza się w dokumentacji konkretnej usługi, zamiast zakładać, że wszystkie interfejsy działają tak samo.
REST jest jednym stylem projektowania API
Nazwa REST często pojawia się obok API, przez co łatwo uznać, że znaczą to samo. API jest pojęciem szerszym, a REST opisuje jeden ze sposobów projektowania interfejsów sieciowych. Istnieją też inne rozwiązania, między innymi GraphQL i SOAP.
W interfejsie REST adresy często wskazują zasoby, na przykład /products/42, a metody HTTP określają rodzaj operacji. GET może pobrać dane, POST wysłać nowe, a DELETE zażądać usunięcia zasobu. Sam zestaw metod nie wystarcza jednak, by rozstrzygnąć, czy API jest REST; szczegóły zależą od zasad przyjętych przy jego projektowaniu.
Przeglądarka ma też własne interfejsy programistyczne. Na przykład Web API udostępniają funkcje pozwalające stronie obsłużyć multimedia lub elementy dokumentu. To inny przypadek niż zdalna usługa, która odbiera żądanie przez sieć. Rozróżnienie opisuje przewodnik MDN o Web API.
401 i 403 podpowiadają, gdzie szukać problemu
Gdy wywołanie API nie działa, komunikat błędu może wskazać, czy brakuje danych logowania, czy konto nie ma wymaganych uprawnień. To rozróżnienie oszczędza czas, bo zmiana kodu nie naprawi braku dostępu po stronie usługi.
| Sytuacja | Możliwa przyczyna | Co sprawdzić |
|---|---|---|
| Odpowiedź 401 | Brak danych uwierzytelniających albo są nieprawidłowe. | Sprawdź token, nagłówek autoryzacji i sposób logowania wymagany przez usługę. |
| Odpowiedź 403 | Serwer rozpoznał żądanie, ale odmawia dostępu do tej operacji lub zasobu. | Sprawdź uprawnienia konta i zakres dostępu przyznany aplikacji. |
| Odpowiedź 200, ale brak oczekiwanych danych | Żądanie zakończyło się powodzeniem, lecz odpowiedź może mieć inną strukturę lub nie zawierać szukanej wartości. | Odczytaj treść odpowiedzi i porównaj pola z dokumentacją API. |
401 i 403 nie oznaczają tego samego. Według dokumentacji MDN dla kodu 401, ten status wskazuje na brak prawidłowych danych uwierzytelniających, a 403 zwykle oznacza, że dostęp jest zabroniony mimo rozpoznania żądania. Interpretacja błędu prowadzi więc do różnych kroków naprawczych.
Klucz API nie zawsze potwierdza tożsamość użytkownika
W dokumentacji często pojawia się klucz API, więc łatwo potraktować go jak uniwersalne hasło. Zwykle służy do rozpoznania aplikacji lub projektu korzystającego z usługi; nie musi uwierzytelniać konkretnej osoby ani określać wszystkich jej uprawnień. To zależy od mechanizmu zabezpieczeń zastosowanego przez dostawcę.
Przykład: strona pobiera publiczne dane pogodowe i wysyła klucz przypisany do aplikacji. Jeśli jednak użytkownik ma zobaczyć prywatne dane z własnego konta, sam klucz aplikacji może nie wystarczyć. Uważam, że właśnie tu początkujący najczęściej mylą „API działa” z „każdy użytkownik ma właściwy dostęp”.
Opis interfejsu pomaga uniknąć zgadywania. Specyfikacja OpenAPI pozwala opisać między innymi dostępne ścieżki, operacje, odpowiedzi i mechanizmy bezpieczeństwa. Jeśli dostawca publikuje taki opis, można z niego wygenerować dokumentację, klienta API albo testy, zamiast ręcznie odtwarzać kontrakt z pojedynczych przykładów.
Przed pierwszym wywołaniem sprawdź trzy rzeczy
API staje się zrozumiałe, gdy przestajesz myśleć o nim jak o tajemniczym dodatku do aplikacji, a zaczynasz widzieć konkretną umowę komunikacyjną. Przed połączeniem własnego kodu z usługą sprawdź dokumentację, wymagane dane dostępu oraz przykładowe odpowiedzi. Wtedy łatwiej odróżnisz błąd w kodzie od odmowy dostępu albo niezgodności formatu.
