Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

moai-ref-api-patterns

/moai-ref-api-patterns

Zawiera referencję wzorców projektowania API REST i GraphQL, konwencji obsługi błędów i walidacji danych wejściowych dla backendu, przy projektowaniu endpointów i przeglądzie kodu serwerowego.

Repozytorium
moai-adk ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
26.10.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
1
Skrypty
0
Komentarze HTML
6
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • SKILL.md zawiera komentarze HTML (6). Nie widać ich w podglądzie Markdown, a model je czyta.

Co robi i kiedy

Zawiera referencję wzorców projektowania API REST i GraphQL, konwencji obsługi błędów i walidacji danych wejściowych dla backendu, przy projektowaniu endpointów i przeglądzie kodu serwerowego.

Oryginalny opis (EN)

REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development. Agent-extending skill that amplifies backend domain work (spawned via Agent(general-purpose) with backend instructions) with production-grade API patterns. Use when designing APIs, implementing endpoints, or reviewing backend code. NOT for: frontend development, DevOps, database schema design, security audits.

Jak działa

  1. Target Spawn
  2. RESTful API Design Conventions
  3. HTTP Status Code Guide
  4. Error Response Format
  5. Pagination Pattern
  6. Input Validation Checklist
  7. Rate Limiting Strategy
  8. API Versioning Strategy
  9. Common Rationalizations
  10. Red Flags
Sekcje z nagłówków SKILL.md, w oryginale · 170 linii, 983 słów
Podgląd SKILL.md
---
name: moai-ref-api-patterns
description: >
  REST/GraphQL API design patterns, error handling conventions, and input validation
  reference for backend development. Agent-extending skill that amplifies backend domain
  work (spawned via Agent(general-purpose) with backend instructions) with production-grade
  API patterns. Use when designing APIs, implementing endpoints, or reviewing backend code.
  NOT for: frontend development, DevOps, database schema design, security audits.

when_to_use: >
  Use for REST/GraphQL API design patterns: endpoint and route design,
  handler structure, request/response conventions, error handling, and
  input validation. Amplifies backend domain work (Agent(general-purpose)
  with backend instructions) with production-grade API patterns.

user-invocable: false
metadata:
  version: "1.0.0"
  category: "domain"
  status: "active"
  updated: "2026-03-30"
  tags: "api, rest, graphql, patterns, backend, reference"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 3000
---

# API Patterns Reference

## Target Spawn

Backend domain work spawned via `Agent(general-purpose)` with backend instructions - Applies these patterns directly to API implementation and review.

## RESTful API Design Conventions

| Principle | Convention | Example |
|-----------|-----------|---------|
| Resource Naming | Plural nouns, lowercase, kebab-case | `/api/v1/user-profiles` |
| Collection | GET returns array with pagination | `GET /users?page=1&limit=20` |
| Single Resource | GET returns object | `GET /users/{id}` |
| Create | POST to collection | `POST /users` |
| Update (full) | PUT to resource | `PUT /users/{id}` |
| Update (partial) | PATCH to resource | `PATCH /users/{id}` |
| Delete | DELETE to resource | `DELETE /users/{id}` |
| Nested Resources | Max 2 levels deep | `/users/{id}/posts` |
| Filtering | Query params | `?status=active&role=admin` |
| Sorting | Sort param | `?sort=-created_at,name` |
| Versioning | URL prefix | `/api/v1/`, `/api/v2/` |

## HTTP Status Code Guide

| Category | Code | When to Use |
|----------|------|-------------|
| Success | 200 OK | Successful GET, PUT, PATCH, DELETE |
| Success | 201 Created | Successful POST (resource created) |
| Success | 204 No Content | Successful DELETE (no body) |
| Client Error | 400 Bad Request | Malformed request, validation failure |
| Client Error | 401 Unauthorized | Missing or invalid authentication |
| Client Error | 403 Forbidden | Authenticated but not authorized |
| Client Error | 404 Not Found | Resource does not exist |
| Client Error | 409 Conflict | Resource state conflict (duplicate) |
| Client Error | 422 Unprocessable | Valid syntax but semantic error |
| Client Error | 429 Too Many | Rate limit exceeded |
| Server Error | 500 Internal | Unexpected server error |
| Server Error | 503 Service Unavailable | Maintenance or overload |

## Error Response Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": [
      {"field": "email", "message": "Must be a valid email address"},
      {"field": "age", "message": "Must be between 0 and 150"}
    ],
    "request_id": "req_abc123"
  }
}
```

Rules:
- Never expose stack traces or internal details in production
- Always include request_id for traceability
- Use consistent error codes (ENUM, not free text)
- Login failures: "Invalid email or password" (never reveal which)

## Pagination Pattern

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}
```

For cursor-based (large datasets):
```json
{
  "data": [...],
  "cursor": {
    "next": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}
```

## Input Validation Checklist

| Validation | Method | Tool |
|-----------|--------|------|
| Type validation | Schema validation | Zod, Joi, pydantic, Go validator |
| Length limits | Min/max constraints | Schema min/max |
| Pattern matching | Regex | Email, URL, phone patterns |
| Range validation | Number/date bounds | min/max values |
| Enumeration | Allowed values | enum types |
| SQL Injection | Parameterized queries | ORM (Prisma, GORM, SQLAlchemy) |
| XSS | HTML escaping | Template engines, DOMPurify |
| Path Traversal | Path normalization | filepath.Clean + whitelist |

## Rate Limiting Strategy

| Target | Limit | Key |
|--------|-------|-----|
| Auth endpoints | 5 req/min | IP |
| General API | 100 req/min | User token |
| File upload | 10 req/hour | User token |
| Public API | 30 req/min | IP |

Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` (on 429).

## API Versioning Strategy

| Strategy | Use Case | Example |
|----------|----------|---------|
| URL prefix | Most APIs | `/api/v1/users` |
| Header | Internal APIs | `Accept: application/vnd.api+json; version=2` |
| Query param | Simple APIs | `/users?version=2` |

Breaking changes that require version bump:
- Removing or renaming fields
- Changing field types
- Removing endpoints
- Changing authentication methods

Non-breaking changes (no version bump needed):
- Adding new optional fields
- Adding new endpoints
- Adding new query parameters

<!-- moai:evolvable-start id="rationalizations" -->
## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "REST naming conventions are just aesthetics" | Consistent resource naming is how clients discover and predict endpoints. Inconsistency multiplies documentation burden. |
| "GraphQL solves over-fetching, so I do not need to design response shapes" | GraphQL shifts complexity to the resolver layer. Poorly designed schemas create N+1 queries and authorization gaps. |
| "Error codes are internal details, clients just need the message" | Clients need machine-readable error codes for programmatic handling. Messages are for humans, codes are for code. |
| "PATCH and PUT are interchangeable" | PATCH applies partial updates; PUT replaces the entire resource. Using them incorrectly breaks idempotency expectations. |
| "I will version the API when it becomes necessary" | Versioning after breaking changes forces emergency migrations. Plan versioning from the first release. |

**Hyrum's Law**: Every observable API behavior will eventually be depended on by clients. Undocumented response fields, error formats, and timing characteristics become implicit contracts.

<!-- moai:evolvable-end -->

<!-- moai:evolvable-start id="red-flags" -->
## Red Flags

- API returns different error formats across endpoints
- Resource names use verbs instead of nouns (e.g., /getUser instead of /users/:id)
- No pagination on list endpoints that can return unbounded results
- Breaking change deployed without API version bump
- GraphQL schema allows unbounded depth or circular queries without limits

<!-- moai:evolvable-end -->

<!-- moai:evolvable-start id="verification" -->
## Verification

- [ ] All endpoints follow consistent naming convention (nouns, plurals, nested resources)
- [ ] Error responses use a standard format with machine-readable error code
- [ ] List endpoints implement pagination with documented limits
- [ ] API versioning strategy present and enforced (URL path, header, or query param)
- [ ] Breaking vs non-breaking change classification documented for recent changes
- [ ] Input validation returns 400 with specific field-level error details

<!-- moai:evolvable-end -->

Wersje

W bazie nie ma innych skilli o nazwie moai-ref-api-patterns.

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki 81b0bbef14cc (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

  • 90moai-domain-backend
    Wspiera tworzenie backendu: projektowanie API, integrację z bazami danych, architekturę mikroserwisów, logikę serwerową, uwierzytelnianie i autoryzację.
  • 100api-design-patterns
    Podaje wzorce projektowania API RESTful, obsługi błędów, wersjonowania i dobrych praktyk, także przy przeglądzie endpointów.
  • 100designing-apis
    Projektuje API REST i GraphQL, w tym endpointy, obsługę błędów, wersjonowanie i dokumentację, oraz ocenia kontrakty API.
  • 90backend-api-development
    Wspiera budowę niezawodnych, skalowalnych API: nowe endpointy, usługi i funkcje backendu, w tym REST, GraphQL, kontrolery i routing.
  • 95api-design-patterns
    Opisuje wzorce projektowania API REST i GraphQL z wersjonowaniem, paginacją, obsługą błędów i zasadami HATEOAS dla usług produkcyjnych.
  • 100api-design
    Podaje dobre praktyki projektowania API REST i GraphQL, w tym specyfikacje OpenAPI i dokumentowanie endpointów.

Uwagi i zgłoszenia

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