Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

api-integration

/api-integration

Podłącza aplikację do backendowego API: pobieranie danych, cache, obsługa błędów i stany ładowania, przy łączeniu z endpointem lub poprawianiu zachowania przy błędach.

Repozytorium
claude-kit ↗
Licencja
MIT
Ostatnia zmiana repozytorium
07.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 07.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Podłącza aplikację do backendowego API: pobieranie danych, cache, obsługa błędów i stany ładowania, przy łączeniu z endpointem lub poprawianiu zachowania przy błędach.

Oryginalny opis (EN)

Wire the app to a backend API — data fetching, caching, error handling, loading states. Use when connecting to an endpoint, adding a fetch layer, or fixing API error and loading behaviour. React-query detail lives in tanstack-react-query-patterns.

Jak działa

  1. Steps
  2. Data-Fetching Conventions
  3. Directory Structure
  4. Common Patterns by Stack
  5. Deterministic Testing Against External APIs (record-replay)
  6. References
Sekcje z nagłówków SKILL.md, w oryginale · 367 linii, 1 554 słów
Podgląd SKILL.md
---
name: api-integration
description: Wire the app to a backend API — data fetching, caching, error handling, loading states. Use when connecting to an endpoint, adding a fetch layer, or fixing API error and loading behaviour. React-query detail lives in tanstack-react-query-patterns.
---

Integrate API for: the invocation request.

## Steps

1. **Identify the API**: Determine the endpoint(s), HTTP method(s), request/response shapes, and authentication requirements for the invocation request.

2. **Define types**: Create typed interfaces for request and response payloads. Co-locate types with the API client module according to the project's conventions.

   ```typescript
   // TypeScript example
   export interface GetItemsParams {
     page: number;
     limit: number;
     status?: 'open' | 'resolved' | 'escalated';
   }

   export interface ItemResponse {
     data: Item[];
     total: number;
     page: number;
   }
   ```

   ```python
   # Python example (Pydantic)
   from pydantic import BaseModel

   class GetItemsParams(BaseModel):
       page: int
       limit: int
       status: str | None = None

   class ItemResponse(BaseModel):
       data: list[Item]
       total: int
       page: int
   ```

3. **Create API client functions**: Place in the project's designated API layer as pure async functions. Use the project's HTTP client.

   ```typescript
   // TypeScript example
   import { httpClient } from '@/lib/httpClient';
   import type { GetItemsParams, ItemResponse } from './types/items';

   export async function getItems(params: GetItemsParams): Promise<ItemResponse> {
     const { data } = await httpClient.get<ItemResponse>('/items', { params });
     return data;
   }

   export async function resolveItem(id: string, resolution: string): Promise<void> {
     await httpClient.post(`/items/${encodeURIComponent(id)}/resolve`, { resolution });
   }
   ```

   ```python
   # Python example (httpx)
   import httpx
   from .schemas import GetItemsParams, ItemResponse

   async def get_items(params: GetItemsParams) -> ItemResponse:
       async with httpx.AsyncClient() as client:
           response = await client.get('/items', params=params.model_dump())
           return ItemResponse.model_validate(response.json())

   async def resolve_item(id: str, resolution: str) -> None:
       async with httpx.AsyncClient() as client:
           await client.post(f'/items/{id}/resolve', json={'resolution': resolution})
   ```

4. **Create data-fetching hooks/functions**: Wrap API calls with the project's caching/state management layer.

   ### Query Pattern (React Query example)
   ```typescript
   import { useQuery } from '@tanstack/react-query';
   import { getItems } from '@/api/items';
   import type { GetItemsParams } from '@/api/types/items';

   export const itemKeys = {
     all: ['items'] as const,
     lists: () => [...itemKeys.all, 'list'] as const,
     list: (params: GetItemsParams) => [...itemKeys.lists(), params] as const,
     details: () => [...itemKeys.all, 'detail'] as const,
     detail: (id: string) => [...itemKeys.details(), id] as const,
   };

   export function useItems(params: GetItemsParams) {
     return useQuery({
       queryKey: itemKeys.list(params),
       queryFn: () => getItems(params),
       staleTime: 5 * 60 * 1000, // 5 minutes
       placeholderData: keepPreviousData,
     });
   }
   ```

   ### Mutation Pattern (React Query example)
   ```typescript
   import { useMutation, useQueryClient } from '@tanstack/react-query';
   import { resolveItem } from '@/api/items';

   export function useResolveItem() {
     const queryClient = useQueryClient();

     return useMutation({
       mutationFn: ({ id, resolution }: { id: string; resolution: string }) =>
         resolveItem(id, resolution),
       onSuccess: () => {
         queryClient.invalidateQueries({ queryKey: itemKeys.all });
       },
     });
   }
   ```

   ### Alternative: Service Layer Pattern (backend or Vue/Angular)
   ```python
   # Python service layer
   from .repository import ItemRepository
   from .schemas import GetItemsParams, ItemResponse

   class ItemService:
       def __init__(self, repo: ItemRepository):
           self.repo = repo

       async def get_items(self, params: GetItemsParams) -> ItemResponse:
           items = await self.repo.find_all(params)
           total = await self.repo.count(params)
           return ItemResponse(data=items, total=total, page=params.page)
   ```

5. **Validate responses at the boundary**: Use a validation library to ensure API responses match expected shapes.

   ```typescript
   // TypeScript with Zod
   import { z } from 'zod';

   const itemResponseSchema = z.object({
     data: z.array(itemSchema),
     total: z.number(),
     page: z.number(),
   });

   export async function getItems(params: GetItemsParams) {
     const { data } = await httpClient.get('/items', { params });
     return itemResponseSchema.parse(data);
   }
   ```

   ```python
   # Python with Pydantic (validation built-in)
   from pydantic import BaseModel, field_validator

   class ItemResponse(BaseModel):
       data: list[Item]
       total: int
       page: int

       @field_validator('total')
       @classmethod
       def total_non_negative(cls, v: int) -> int:
           if v < 0:
               raise ValueError('total must be non-negative')
           return v
   ```

6. **Use in components/views**: Follow the loading/empty/error state pattern.

   ```tsx
   // React example
   function ItemList() {
     const { data, isLoading, error } = useItems({ page: 1, limit: 20 });

     if (isLoading) return <Spinner />;
     if (error) return <EmptyState title="Failed to load items" />;
     if (!data?.data.length) return <EmptyState title="No items found" />;

     return (
       <div className="space-y-3">
         {data.data.map((item) => (
           <ItemCard key={item.id} item={item} />
         ))}
       </div>
     );
   }
   ```

   ```python
   # Python (FastAPI) example
   from fastapi import APIRouter, Depends, HTTPException, status

   @router.get('/items', response_model=ItemResponse)
   async def list_items(
       params: GetItemsParams = Depends(),
       service: ItemService = Depends(),
   ) -> ItemResponse:
       try:
           return await service.get_items(params)
       except Exception as e:
           raise HTTPException(
               status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
               detail='Failed to load items'
           )
   ```

7. **Verify**: Run the project's linter, type checker, and build to confirm all checks pass.

## Data-Fetching Conventions

### Cache Key Factory
Every feature should have a key factory object for consistent cache management (applies to client-side caching libraries like TanStack Query, SWR, Apollo):

```typescript
export const featureKeys = {
  all: ['feature'] as const,
  lists: () => [...featureKeys.all, 'list'] as const,
  list: (params: Params) => [...featureKeys.lists(), params] as const,
  details: () => [...featureKeys.all, 'detail'] as const,
  detail: (id: string) => [...featureKeys.details(), id] as const,
};
```

### Stale Time Defaults (Client-Side Caching)
| Data Type | Stale Time | Rationale |
|-----------|-----------|-----------|
| Reference data (categories, roles) | 30 minutes | Rarely changes |
| Dashboard KPIs | 5 minutes | Moderate freshness |
| Real-time feeds (notifications, alerts) | 1 minute | Needs frequent updates |
| User-specific (preferences) | Infinity | Only changes on mutation |

### Error Handling
- Use the data-fetching layer's built-in error state — avoid wrapping in try/catch at the component level
- Global error handler for auth errors (401 → redirect to login)
- Show empty/error state UI for query failures
- Show toast/notification for mutation failures

### Optimistic Updates (Client-Side)
Use for operations where the user expects instant feedback:

```typescript
// TanStack Query example
onMutate: async (newData) => {
  await queryClient.cancelQueries({ queryKey });
  const previous = queryClient.getQueryData(queryKey);
  queryClient.setQueryData(queryKey, (old) => /* optimistic update */);
  return { previous };
},
onError: (_err, _new, context) => {
  queryClient.setQueryData(queryKey, context?.previous);
},
onSettled: () => {
  queryClient.invalidateQueries({ queryKey });
},
```

```python
# Backend optimistic approach (return before commit)
async def update_item(db: AsyncSession, id: str, update: ItemUpdate) -> Item:
    item = await repo.get_by_id(db, id)
    if not item:
        raise HTTPException(status_code=404)

    # Apply changes
    for field, value in update.model_dump(exclude_unset=True).items():
        setattr(item, field, value)

    # Flush to get updated state, but don't commit yet
    await db.flush()
    await db.refresh(item)

    # Return optimistically (commit happens at end of request)
    return item
```

## Directory Structure

Adapt to your project's conventions. Common patterns:

### Frontend (React/Vue/Angular)
```
src/
  lib/
    httpClient.ts                        # Shared HTTP client (Axios/Fetch)
    queryKeys.ts                         # Shared query key factories (if using client-side caching)
  providers/
    QueryProvider.tsx                    # Data-fetching provider (TanStack Query, SWR, Apollo)
  modules/ (or features/)
    <feature>/
      api/<feature>Api.ts                # Plain async API functions
      hooks/use<Feature>Queries.ts       # Data-fetching hooks wrapping API functions
      types/<feature>.ts                 # Request/response types
```

### Backend (Python/Node/Go/etc.)
```
app/
  api/                                   # HTTP route handlers
    v1/
      <feature>/
        router.py (or routes.ts)         # Route definitions
        schemas.py (or dtos.ts)          # Request/response schemas
        service.py (or service.ts)       # Business logic
        repository.py (or repository.ts) # Data access
```

**Key rules:**
- API client functions (plain async) live in the project's designated API layer
- Data-fetching hooks/wrappers live alongside the module or in a dedicated hooks folder
- Key factories can be co-located or centralized depending on the project's conventions
- Validation happens at system boundaries (API responses in frontend, request payloads in backend)

## Common Patterns by Stack

### React + TanStack Query
- Query hooks: `useQuery` for reads, `useMutation` for writes
- Key factories for cache management
- `invalidateQueries` after mutations
- `placeholderData: keepPreviousData` for pagination

### Vue + Pinia
- API functions in composables (`useItems`)
- Pinia store for caching if needed
- Loading/error state in composable return

### Angular + RxJS
- API functions return Observables
- Service layer manages HTTP calls
- `catchError` for error handling
- `shareReplay` for caching

### Backend (FastAPI/Express/Spring Boot)
- Repository pattern for data access
- Service layer for business logic
- Route handlers delegate to services
- Typed request/response schemas

## Deterministic Testing Against External APIs (record-replay)

Tests that hit a live third-party API are slow, flaky, rate-limited, and fail when you're offline or the
vendor has an incident — yet hand-written mocks drift out of sync with the real contract and quietly stop
reflecting it. The **record-replay** pattern gets both fidelity and determinism:

- **Record once against the real API**, capturing each request→response pair to a fixture (a "cassette"),
  then **replay** from fixtures on every subsequent run — no network, fast, deterministic, CI-friendly.
- **Redact secrets at record time.** Strip `Authorization`, API keys, cookies, and any PII from the
  saved request/response before it lands in the repo — fixtures are committed and must never carry
  credentials (ties to the security-and-hardening skill and `secret-scanner`).
- **Match requests deliberately and re-record on drift.** Decide what identifies a recorded interaction
  (method + path + significant query/body), and **periodically re-record** so the fixtures track the
  live contract instead of rotting — a stale cassette is a mock in disguise. Pair with a real
  contract/integration check on a schedule so drift is caught.
- Most ecosystems have a record-replay library — VCR (Ruby), `vcrpy` / `pytest-recording` (Python),
  Polly.js / `nock` back: recordings (JS), WireMock (JVM), or a standalone record-replay proxy in front
  of the system under test. The *pattern* is the point, not any one tool.

> Stack-agnostic adaptation of the record-replay proxy pattern for deterministic external-API testing
> (record real responses with secrets redacted → replay offline → re-record on drift) from the
> Apache-2.0 [`google/test-server`](https://github.com/google/test-server). Re-derived in prose; not
> vendored — the pattern is implemented by record-replay libraries across ecosystems.

## References

- HTTP client: Check the project's configuration (Axios, Fetch, httpx, requests)
- Data-fetching library: TanStack Query, SWR, Apollo (frontend), or service/repository pattern (backend)
- Validation: Zod, Yup, io-ts (TypeScript), Pydantic (Python), Joi (Node.js)
- Loading/error patterns: Check `code-organization.md` for the project's UI component conventions
Pliki w paczce (2)
  • SKILL.md 13 KB
  • agents/openai.yaml 1 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · ajyadav013/claude-kit100MIT
facebook/agentic-tools100MIT
mhmdelgazzar/agentex100MIT
AutumnsGrove/Lattice100AGPL-3.0
srstomp/pokayokay100MIT
ajyadav013/claude-kit100MIT
seb1n/awesome-ai-agent-skills100MIT
shurikentrade/shuriken-skills100MIT
LambdaTest/agent-skills95MIT

Migawka bazy z 13.11.2026 · wersja paczki d551a59b84b3 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100expo-data-fetching
    Pomaga implementować i debugować zapytania sieciowe w React Native: fetch, React Query, SWR, obsługa błędów, cache, tryb offline, stany ekranów i loadery Expo Router.
  • 100react-ui-patterns
    Opisuje nowoczesne wzorce UI w React dla stanów ładowania, obsługi błędów i pobierania danych asynchronicznych.
  • 100react-ui-patterns
    Opisuje nowoczesne wzorce UI w React dla stanów ładowania, obsługi błędów i pobierania danych asynchronicznych.
  • 100react-ui-patterns
    Opisuje nowoczesne wzorce UI w React dla stanów ładowania, obsługi błędów i pobierania danych asynchronicznych.
  • 100native-data-fetching
    Pomaga implementować i debugować żądania sieciowe i pobieranie danych: fetch API, React Query, SWR, obsługa błędów, cache, tryb offline i loadery danych Expo Router.
  • 100rn-data-fetching
    Prowadzi przez pobieranie danych z API w React Native z TanStack Query: zapytania, mutacje, aktualizacje optymistyczne, listy z paginacją, unieważnianie cache i obsługę stanów ładowania.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.