Wzorce rozwoju API

Opanuj rozwój API z Cursor i Claude Code. Te wzorce obejmują REST, GraphQL, gRPC, zasady projektowania API, strategie wersjonowania, bezpieczeństwo, dokumentację i podejścia do testowania zoptymalizowane dla rozwoju wspomaganego przez AI.

Podstawy projektowania API

Projektowanie RESTful API

Cursor

1. Otwórz Cursor w swoim projekcie
2. Aktywuj tryb Agent (Cmd/Ctrl + I)
3. Prompt: “Zaprojektuj RESTful API dla zarządzania zadaniami z:
   • URL-ami opartymi na zasobach
   • Właściwymi metodami HTTP
   • Kodami statusu
   • Linkami HATEOAS
   • Paginacją
   • Filtrowaniem i sortowaniem”
4. Agent tworzy kompletną specyfikację API

Claude Code

1. Uruchom: claude "Utwórz specyfikację OpenAPI 3.0 dla API e-commerce"
2. Claude zaprojektuje:
   • Endpointy RESTful
   • Schematy żądań/odpowiedzi
   • Metody uwierzytelniania
   • Standardy obsługi błędów

Wzorce REST API

Projektowanie zasobów

# Prompt projektowania API:
"Zaprojektuj zasoby REST dla platformy blogowej:
- Zasoby hierarchiczne (/blogs/{id}/posts/{id}/comments)
- Relacje zasobów
- Spójne konwencje nazewnictwa
- Endpointy akcji dla operacji niebędących CRUD
- Operacje zbiorcze
- Operacje asynchroniczne z endpointami statusu"

Zaawansowane funkcje REST

Hypermedia

// Prompt: "Dodaj linki HATEOAS:
// - Nawigacja po zasobach
// - Dostępne akcje
// - Powiązane zasoby
// - Linki paginacji"

Negocjacja treści

# Prompt: "Zaimplementuj negocjację treści:
# - Wiele formatów odpowiedzi
# - Wybór języka
# - Negocjacja wersji
# - Wsparcie kompresji"

Wskazówka

Przy projektowaniu REST API, poproś AI o przestrzeganie poziomu dojrzałości REST 3 (HATEOAS) dla maksymalnej elastyczności i wykrywalności.

Wzorce GraphQL API

Projektowanie schematu

# Prompt schematu GraphQL:
"Zaprojektuj schemat GraphQL dla sieci społecznościowej:
- Typy użytkowników z relacjami
- Ograniczanie złożoności zapytań
- Dataloader dla zapobiegania N+1
- Subskrypcje dla aktualizacji w czasie rzeczywistym
- Niestandardowe skalary
- Wsparcie federacji"

Wzorce resolverów

Optymalizacja zapytań

// Prompt optymalizacji resolverów:
"Zoptymalizuj resolvery GraphQL z:
- Ładowaniem wsadowym
- Strategiami cache'owania
- Ograniczaniem głębokości zapytań
- Uprawnieniami na poziomie pól
- Obsługą błędów"

Mutacje

// Wzorce mutacji:
"Zaimplementuj mutacje z:
- Walidacją wejścia
- Optymistycznymi aktualizacjami
- Typami błędów
- Obsługą efektów ubocznych
- Emitowaniem zdarzeń"

Wzorce gRPC

Definicja serwisu

// Prompt serwisu gRPC:
"Utwórz serwis gRPC dla przetwarzania płatności:
- Definicje Protocol Buffer
- Metody serwisu (unary, streaming)
- Obsługa błędów z kodami statusu
- Interceptory dla auth/logowania
- Sprawdzanie zdrowia
- Wsparcie równoważenia obciążenia"

Zaawansowane funkcje gRPC

1. Streaming: “Zaimplementuj dwukierunkowy streaming dla czatu”
2. Interceptory: “Dodaj interceptory auth i logowania”
3. Obsługa błędów: “Utwórz bogate szczegóły błędów”
4. Wydajność: “Zoptymalizuj z poolingiem połączeń”

Wersjonowanie API

Strategie wersjonowania

// Prompt implementacji wersjonowania:
"Zaimplementuj wersjonowanie API z:
- Wersjonowaniem URL (/v1/, /v2/)
- Wersjonowaniem nagłówków
- Negocjacją treści
- Nagłówkami sunset
- Przewodnikami migracji
- Kompatybilnością wsteczną"

Zarządzanie wersjami

AI może pomóc z:

• Strategiami wycofywania
• Ścieżkami migracji wersji
• Flagami funkcji dla stopniowego wdrażania
• Wykrywaniem kompatybilności klienta
• Aktualizacjami dokumentacji

Uwierzytelnianie i autoryzacja

Implementacja OAuth 2.0

// Prompt implementacji OAuth:
"Zaimplementuj OAuth 2.0 z:
- Przepływem authorization code
- Rotacją refresh token
- PKCE dla klientów publicznych
- Zarządzaniem zakresami
- Introspektywaniem tokenów
- Endpointami odwołania"

Wzorce bezpieczeństwa API

JWT

// Implementacja JWT:
"Skonfiguruj auth JWT z:
- Generowaniem tokenów
- Walidacją claims
- Strategią odświeżania
- Blacklistowaniem
- Rotacją kluczy"

Klucze API

// System kluczy API:
"Utwórz zarządzanie kluczami API:
- Generowanie kluczy
- Ograniczanie częstotliwości per klucz
- Ograniczenia zakresu
- Analitykę użycia
- Rotację kluczy"

Ograniczanie częstotliwości i throttling

Strategie implementacji

// Prompt ograniczania częstotliwości:
"Zaimplementuj ograniczanie częstotliwości z:
- Algorytmem token bucket
- Licznikami sliding window
- Rozproszonym ograniczaniem częstotliwości
- Limitami opartymi na użytkownikach
- Limitami specyficznymi dla endpointów
- Graceful degradation"

Uwaga

Zawsze implementuj nagłówki ograniczania częstotliwości (X-RateLimit-*), aby pomóc klientom w zarządzaniu wzorcami żądań.

Dokumentacja API

OpenAPI/Swagger

# Prompt dokumentacji:
"Wygeneruj dokumentację OpenAPI z:
- Kompletnymi definicjami schematu
- Przykładami żądań/odpowiedzi
- Szczegółami uwierzytelniania
- Odpowiedziami błędów
- Specyfikacjami webhooków
- Endpointami testowymi"

Najlepsze praktyki dokumentacji

Interaktywne docs

// Prompt: "Utwórz Swagger UI z:
// - Funkcją try-it-out
// - Generowaniem kodu
// - Wieloma językami
// - Przełączaniem środowisk"

Generowanie SDK

// Prompt: "Wygeneruj SDK klientów:
// - TypeScript/JavaScript
// - Python
// - Go
// - Java
// Z właściwą obsługą błędów"

Obsługa błędów

Spójne odpowiedzi błędów

// Prompt obsługi błędów:
"Zaprojektuj format odpowiedzi błędów:
{
  'error': {
    'code': 'RESOURCE_NOT_FOUND',
    'message': 'Użytkownik nie znaleziony',
    'details': {...},
    'timestamp': '2024-01-01T00:00:00Z',
    'traceId': 'abc123'
  }
}

Uwzględnij:
- Standardowe kody błędów
- Zlokalizowane komunikaty
- Informacje debugowe
- Sugestie naprawy"

Wzorce paginacji

Strategie paginacji

Oparta na offset

# Paginacja offset:
"Zaimplementuj paginację offset:
- Parametry page i limit
- Całkowita liczba w odpowiedzi
- Nagłówki Link
- Wymuszanie maksymalnego limitu"

Oparta na kursorze

# Paginacja kursorem:
"Zaimplementuj paginację kursorem:
- Nieprzezroczyste tokeny kursora
- Stabilne sortowanie
- Efektywne zapytania
- Nawigacja dwukierunkowa"

Webhooks i zdarzenia

Implementacja webhooków

// Prompt systemu webhooków:
"Utwórz system webhooków z:
- Rejestracją zdarzeń
- Podpisywaniem payload
- Logiką ponawiania
- Kolejką dead letter
- Filtrowaniem zdarzeń
- Śledzeniem dostarczania"

1. Projektowanie zdarzeń: “Zdefiniuj schemat i typy zdarzeń”
2. Implementacja dostarczania: “Utwórz niezawodny system dostarczania”
3. Dodawanie bezpieczeństwa: “Zaimplementuj weryfikację podpisu HMAC”
4. Monitorowanie zdrowia: “Śledź wskaźniki sukcesu dostarczania”

Testowanie API

Kompleksowe testowanie

// Prompt testowania API:
"Utwórz zestaw testów API z:
- Testowaniem kontraktów
- Testami integracyjnymi
- Testami obciążenia
- Testami bezpieczeństwa
- Serwisami mock
- Zarządzaniem danymi testowymi"

Strategie testowania

Automatyzacja testów

AI może wygenerować:

• Kolekcje Postman
• Integrację Newman CI
• Testy kontraktowe Pact
• Testy wydajnościowe K6
• Konfiguracje skanowania bezpieczeństwa

Strategie cache’owania

Cache’owanie HTTP

# Implementacja cache'owania:
"Zaimplementuj cache'owanie HTTP z:
- Generowaniem ETag
- Nagłówkami Cache-Control
- Żądaniami warunkowymi
- Integracją CDN
- Invalidacją cache
- Nagłówkami Vary"

Monitorowanie i analityka

Obserwowalność API

// Prompt monitorowania:
"Skonfiguruj monitorowanie API z:
- Logowaniem żądań/odpowiedzi
- Metrykami wydajności
- Śledzeniem błędów
- Analityką użycia
- Monitorowaniem SLA
- Regułami alertów"

Wskazówka

Zaimplementuj correlation ID dla wszystkich żądań API, aby umożliwić skuteczne rozproszone śledzenie i debugowanie.

Wzorce API Gateway

Implementacja gateway

# Prompt API gateway:
"Skonfiguruj API gateway dla:
- Routingu żądań
- Uwierzytelniania
- Ograniczania częstotliwości
- Transformacji żądań/odpowiedzi
- Circuit breaking
- Service discovery"

Najlepsze praktyki z AI

Skuteczne prompty API

// Strukturyzuj prompty jak:
"Zaprojektuj API [REST/GraphQL/gRPC] dla [domeny] z:
- Przypadkami użycia: [lista konkretnych operacji]
- Wymaganiami wydajności: [SLA]
- Potrzebami bezpieczeństwa: [metoda auth]
- Punktami integracji: [serwisy zewnętrzne]
- Uwzględnij przykłady i przypadki brzegowe"

Przegląd projektowania API

Przegląd projektu

AI może sprawdzić:

• Zasady RESTful
• Luki bezpieczeństwa
• Problemy wydajności
• Braki w dokumentacji

Generowanie kodu

AI może wygenerować:

• Klientów API
• Stuby serwerów
• Zestawy testów
• Dokumentację

Zaawansowane wzorce

API oparte na zdarzeniach

// API oparte na zdarzeniach:
"Zaimplementuj API oparte na zdarzeniach z:
- Server-sent events
- Wsparciem WebSocket
- Event sourcing
- Wzorcem CQRS
- Replay zdarzeń
- Rejestrem schematów"

Kompozycja API

// Wzorzec kompozycji API:
"Utwórz warstwę kompozycji API:
- Backend for frontend (BFF)
- Agregacja serwisów
- Transformacja odpowiedzi
- Strategie fallback
- Koordynacja cache"

Następne kroki

• Odkryj wzorce serverless dla wdrażania API
• Naucz się wzorców testowania dla testowania API
• Opanuj wzorce DevOps dla operacji API