API określa, jak jeden program prosi inny o dane lub wykonanie działania. Dzięki temu strona może utworzyć kontakt w CRM, operator płatności przekazać wynik, a aplikacja mobilna odczytać stan konta. Dobre API nie jest tylko zbiorem adresów: to umowa dotycząca danych, uprawnień, błędów i zasad wprowadzania zmian.
Projektuj wokół rzeczywistych działań
Zacznij od zdarzeń biznesowych i rekordów potrzebnych integracji. Nazywaj operacje jednoznacznie i zwracaj tylko wymagane informacje. Opisz poprawne dane wejściowe, możliwe odpowiedzi i błędy. Dokumentacja oraz przykłady powinny odzwierciedlać działającą usługę, a nie dawną wersję specyfikacji.
Bezpieczeństwo należy do umowy
Uwierzytelniaj wywołujących i sprawdzaj prawo do konkretnego rekordu, a nie tylko ogólną rolę użytkownika. Ograniczaj liczbę żądań i waliduj każde wejście. Tajne tokeny trzymaj na zaufanych serwerach. Zapisuj działania zmieniające płatności, uprawnienia albo dane klientów.
Przygotuj się na zawodną sieć
Żądanie może przekroczyć limit czasu, choć druga usługa wykonała już operację. Ważne zapisy projektuj idempotentnie: ponowienie nie może tworzyć podwójnych zamówień ani obciążeń. Ustal limity czasu i zasady ponawiania. Przy zdarzeniach zapisuj próby dostarczenia i umożliwiaj ponowne przetworzenie nieudanych.
Zaplanuj zmiany
Klienci i usługi rzadko aktualizują się jednocześnie. W miarę możliwości wprowadzaj zgodne rozszerzenia, świadomie wersjonuj zmiany niekompatybilne i obserwuj, kto nadal korzysta ze starego zachowania. Utrzymane API pozwala rozwijać produkt bez tworzenia kruchego wyjątku dla każdej integracji.
