Czym jest API ?

• javascript
• typescript

Aby się porozumieć, muszą ustalić:

• Medium komunikacji (np. e-mail, telefon).
• Język komunikacji (np. angielski jako wspólny język).
• Format wiadomości (np. temat + treść).

Podobnie działają programy – mimo różnych środowisk i języków programowania mogą wymieniać dane dzięki wcześniej ustalonym zasadom. Takie reguły określa API, które definiuje, jakie dane można przesyłać, w jakim formacie i jakie akcje są dostępne. Dzięki temu systemy mogą się efektywnie komunikować.

Dobre praktyki przy tworzeniu API pomagają zespołom programistycznym ustalić, w jaki sposób programy wymieniają się informacjami. Przykładowo, w API często stosuje się standardowe metody REST API, które opisują intencję żądań, takie jak:

• GET – pobranie danych,
• POST – utworzenie nowych danych,
• PUT – aktualizacja istniejących danych,
• DELETE – usunięcie danych.

Choć są to uznane dobre praktyki, w rzeczywistości programiści mogą ustalić własne zasady. Na przykład mogą zdecydować, że zamiast metody DELETE będą używać własnej, niestandardowej metody o nazwie KUPA, która będzie usuwać dane. API działa wówczas tak, jak ustalą programiści – zgodnie z ich “umową”. To ogromna elastyczność, ale wymaga jasnej dokumentacji.

Jak działają metody API?

Metody API definiują, co żądanie ma zrobić z danymi. W środowisku REST API, bazującym na protokole HTTP, najczęściej stosuje się cztery podstawowe metody, znane również jako “CRUD” (od angielskich Create, Read, Update, Delete). Oto ich szerszy opis:

1. GET – Pobranie danych

Metoda GET służy do odczytywania danych. Za pomocą tej metody aplikacja kliencka (np. przeglądarka internetowa lub aplikacja mobilna) wysyła żądanie do serwera, prosząc o udostępnienie określonych informacji.

Przykład:

• Klient wysyła żądanie do serwera: GET /user/1.
• Serwer odpowiada, zwracając dane użytkownika o ID = 1, np.:

Zastosowania:

• Pobranie listy produktów w sklepie internetowym.
• Wyświetlenie profilu użytkownika.
• Pobranie pogody z serwera meteorologicznego.

2. POST – Tworzenie nowych danych

Metoda POST umożliwia wysyłanie danych do serwera w celu utworzenia nowych zasobów. Klient przesyła dane w treści żądania, a serwer tworzy nowy rekord w swojej bazie.

Przykład:

• Klient wysyła żądanie: POST /user z treścią:

• Serwer tworzy nowego użytkownika i zwraca odpowiedź z informacją o nowym zasobie:

Zastosowania:

• Rejestracja nowego użytkownika.
• Dodanie nowego produktu do katalogu.
• Wysłanie komentarza w serwisie społecznościowym.

3. PUT – Aktualizacja danych

Metoda PUT służy do aktualizacji istniejących danych. Klient przesyła żądanie z kompletnymi, zaktualizowanymi danymi, które mają zastąpić obecne dane na serwerze.

Przykład:

• Klient wysyła żądanie: PUT /user/1 z treścią:

• Serwer aktualizuje dane użytkownika o ID = 1.

Zastosowania:

• Edytowanie profilu użytkownika.
• Aktualizacja informacji o produkcie.
• Zmiana statusu zamówienia.

4. DELETE – Usuwanie danych

Metoda DELETE jest używana do usuwania danych na serwerze. Po otrzymaniu żądania serwer usuwa wskazany zasób.

Przykład:

• Klient wysyła żądanie: DELETE /user/1.
• Serwer usuwa dane użytkownika o ID = 1 i zwraca odpowiedź potwierdzającą operację.

Zastosowania:

• Usuwanie konta użytkownika.
• Usuwanie komentarza w aplikacji społecznościowej.
• Kasowanie danych z systemu rezerwacji.

Elastyczność metod API

Wspomniane metody GET, POST, PUT i DELETE to standardowe, szeroko stosowane praktyki w API. Jednak nic nie stoi na przeszkodzie, aby zdefiniować własne metody. Przykładowo, zespoły programistyczne mogą umówić się, że metoda KUPA będzie używana do usuwania danych. Choć jest to technicznie możliwe, warto trzymać się standardów, aby API było czytelne i łatwe do integracji dla innych zespołów.

Dobre praktyki przy tworzeniu metod API

1. Zrozumiała dokumentacja – Każda metoda powinna być dobrze opisana, aby użytkownicy API wiedzieli, co dokładnie robi.
2. Idempotentność – Metody, takie jak GET, PUT czy DELETE, powinny być idempotentne, co oznacza, że wielokrotne wywołanie tej samej metody z tymi samymi danymi powinno dawać ten sam rezultat.
3. Zabezpieczenia – Metody API powinny być zabezpieczone przed nieautoryzowanym dostępem, np. za pomocą OAuth czy kluczy API.
4. Kody odpowiedzi HTTP – API powinno zwracać odpowiednie kody statusu (np. 200 dla sukcesu, 404 dla braku zasobu, 500 dla błędu serwera), aby użytkownik wiedział, co się dzieje.