api-integration
/api-integration
Łączy aplikację z backendowym API: pobieranie danych, cache, obsługa błędów i stany ładowania, przy podpinaniu endpointu, dodawaniu warstwy fetch lub naprawie zachowania przy błędach.
- Autor
- ajyadav013 ↗
- Repozytorium
- claude-kit ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 07.09.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 07.09.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Łączy aplikację z backendowym API: pobieranie danych, cache, obsługa błędów i stany ładowania, przy podpinaniu endpointu, dodawaniu warstwy fetch lub naprawie zachowania przy błędach.
Argumenty
/api-integration [API endpoint or feature name]
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
- Steps
- Data-Fetching Conventions
- Directory Structure
- Common Patterns by Stack
- Deterministic Testing Against External APIs (record-replay)
- References
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.
argument-hint: '[API endpoint or feature name]'
disable-model-invocation: true
---
Integrate API for: $ARGUMENTS.
## Steps
1. **Identify the API**: Determine the endpoint(s), HTTP method(s), request/response shapes, and authentication requirements for $ARGUMENTS.
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 `.claude/skills/security-and-hardening` 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
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · ajyadav013/claude-kit | 100 | MIT |
| facebook/agentic-tools | 100 | MIT |
| mhmdelgazzar/agentex | 100 | MIT |
| AutumnsGrove/Lattice | 100 | AGPL-3.0 |
| srstomp/pokayokay | 100 | MIT |
| ajyadav013/claude-kit | 100 | MIT |
| seb1n/awesome-ai-agent-skills | 100 | MIT |
| shurikentrade/shuriken-skills | 100 | MIT |
| LambdaTest/agent-skills | 95 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 56966878eb2b (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. - 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. - 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.