Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

rest-api

/rest-api

Projektuje i buduje REST API: endpointy, CRUD, uwierzytelnianie, paginację, wersjonowanie, dokumentację OpenAPI, rate limiting, middleware i CORS w Express, Fastify, Koa, Flask lub FastAPI.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
25.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
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.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 robi i kiedy

Projektuje i buduje REST API: endpointy, CRUD, uwierzytelnianie, paginację, wersjonowanie, dokumentację OpenAPI, rate limiting, middleware i CORS w Express, Fastify, Koa, Flask lub FastAPI.

Oryginalny opis (EN)

Design and build RESTful APIs. Use when a user asks to create a REST API, design API endpoints, implement CRUD operations, add authentication to an API, handle pagination and filtering, set up API versioning, generate OpenAPI/Swagger docs, implement rate limiting, build middleware, handle file uploads, add CORS, implement HATEOAS, or structure an Express/Fastify/Koa/Flask/FastAPI backend. Covers HTTP methods, status codes, resource modeling, error handling, validation, and production deployment patterns.

Jak działa

  1. Overview
  2. Instructions
  3. Examples
  4. Guidelines
Sekcje z nagłówków SKILL.md, w oryginale · 218 linii, 1 165 słów
Podgląd SKILL.md
---
name: rest-api
description: >-
  Design and build RESTful APIs. Use when a user asks to create a REST API,
  design API endpoints, implement CRUD operations, add authentication to an API,
  handle pagination and filtering, set up API versioning, generate
  OpenAPI/Swagger docs, implement rate limiting, build middleware, handle file
  uploads, add CORS, implement HATEOAS, or structure an
  Express/Fastify/Koa/Flask/FastAPI backend. Covers HTTP methods, status codes,
  resource modeling, error handling, validation, and production deployment
  patterns.
license: Apache-2.0
compatibility: 'Node.js 18+ (Express, Fastify) or Python 3.9+ (FastAPI, Flask)'
metadata:
  author: terminal-skills
  version: 1.1.0
  category: development
  tags: "rest, api, express, fastapi, openapi"
---

# REST API

## Overview

Design and build production-grade RESTful APIs following industry conventions. This skill covers resource modeling, HTTP semantics, authentication, validation, pagination, versioning, documentation, error handling, and security — with examples in Express (Node.js) and FastAPI (Python).

## Instructions

### Step 1: Project Setup

**Express:**
```bash
npm install express@5 cors helmet morgan compression zod jsonwebtoken bcrypt swagger-jsdoc swagger-ui-express
```

**FastAPI** (the FastAPI security tutorial now uses PyJWT and pwdlib; python-jose and passlib are no longer maintained):
```bash
pip install "fastapi[standard]" uvicorn sqlalchemy pydantic-settings pyjwt "pwdlib[argon2]"
# Commit the lockfile (package-lock.json / uv.lock or a pinned requirements.txt) and install from it
# in CI and production (`npm ci`, `pip install -r requirements.txt`) for exact, integrity-checked versions.
```

### Step 2: Resource Design

```
Resource        Endpoint                    Methods
Users           /api/v1/users               GET, POST
User            /api/v1/users/:id           GET, PUT, PATCH, DELETE
User Posts      /api/v1/users/:id/posts     GET
Posts           /api/v1/posts               GET, POST
Post Comments   /api/v1/posts/:id/comments  GET, POST
```

Rules: plural nouns (`/users`), no verbs in URLs, max 2 nesting levels, kebab-case (`/user-profiles`).

### Step 3: HTTP Methods and Status Codes

```
Method   Purpose          Success Code   Body
GET      Read             200 OK         Resource/collection
POST     Create           201 Created    Created resource + Location header
PUT      Full replace     200 OK         Updated resource
PATCH    Partial update   200 OK         Updated resource
DELETE   Remove           204 No Content (empty)

Key error codes: 400 (bad input), 401 (unauthenticated), 403 (forbidden),
404 (not found), 409 (conflict), 422 (validation), 429 (rate limited)
```

### Step 4: Express Implementation

```javascript
// src/app.js
import express from 'express';
import cors from 'cors';
import helmet from 'helmet';

const app = express();
app.use(helmet());
app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(',') ?? false }));
app.use(express.json({ limit: '10kb' }));
app.use('/api/v1/users', usersRouter);
app.get('/health', (req, res) => res.json({ status: 'ok' }));
app.use(notFound);
app.use(errorHandler);
```

```javascript
// src/routes/users.js — validation with Zod
import { Router } from 'express';
import { z } from 'zod';

const createUserSchema = z.object({
  body: z.object({
    email: z.email(),
    name: z.string().min(2).max(100),
    password: z.string().min(8).max(128),
  }),
});

router.get('/',       authenticate, validate(listSchema), usersController.list);
router.post('/',      validate(createUserSchema),          usersController.create);
router.get('/:id',    authenticate,                        usersController.getOne);
router.patch('/:id',  authenticate, validate(updateSchema), usersController.update);
router.delete('/:id', authenticate, authorize('admin'),    usersController.remove);
```

```javascript
// src/controllers/users.js
export async function list(req, res) {
  const { page, limit, sort, search } = req.validated.query; // coerced and defaulted by Zod
  const [users, total] = await Promise.all([
    db.user.findMany({ where: search ? { name: { contains: search } } : {}, skip: (page - 1) * limit, take: limit }),
    db.user.count(),
  ]);
  res.json({ data: users, meta: { page, limit, total, totalPages: Math.ceil(total / limit) } });
}

export async function create(req, res) {
  const existing = await db.user.findUnique({ where: { email: req.body.email } });
  if (existing) throw new AppError(409, 'Email already registered');
  const user = await db.user.create({ data: { ...req.body, password: await hashPassword(req.body.password) } });
  res.status(201).location(`/api/v1/users/${user.id}`).json({ data: user });
}
```

### Step 5: Middleware (Auth, Validation, Errors)

```javascript
// Auth
export function authenticate(req, res, next) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) throw new AppError(401, 'Missing token');
  try { req.user = jwt.verify(header.slice(7), process.env.JWT_SECRET); next(); }
  catch { throw new AppError(401, 'Invalid token'); }
}

// Validation
export function validate(schema) {
  return (req, res, next) => {
    const result = schema.safeParse({ body: req.body, query: req.query, params: req.params });
    if (!result.success) throw new AppError(400, 'Validation failed', result.error.issues);
    req.validated = result.data; // Express 5: req.query is read-only, so never assign to it
    next();
  };
}

// Error handler
export function errorHandler(err, req, res, next) {
  const status = err.statusCode || 500;
  res.status(status).json({
    error: { code: err.code || 'INTERNAL_ERROR', message: status === 500 ? 'Internal server error' : err.message },
  });
}
```

### Step 6: FastAPI Implementation

```python
from datetime import datetime
from fastapi import FastAPI, APIRouter, Depends, HTTPException, Query
from pydantic import BaseModel, EmailStr, Field

app = FastAPI(title="Orbit Projects API", version="1.0.0", docs_url="/api/docs", redoc_url="/api/redoc")

class UserCreate(BaseModel):
    email: EmailStr
    name: str = Field(min_length=2, max_length=100)
    password: str = Field(min_length=8, max_length=128)

class UserResponse(BaseModel):
    id: str; email: str; name: str; created_at: datetime
    model_config = {"from_attributes": True}

router = APIRouter()

@router.get("", response_model=PaginatedResponse[UserResponse])
async def list_users(page: int = Query(1, ge=1), limit: int = Query(20, ge=1, le=100), db=Depends(get_db)):
    users, total = await user_service.get_many(db, page=page, limit=limit)
    return {"data": users, "meta": {"page": page, "limit": limit, "total": total}}

@router.post("", response_model=UserResponse, status_code=201)
async def create_user(body: UserCreate, db=Depends(get_db)):
    existing = await user_service.get_by_email(db, body.email)
    if existing: raise HTTPException(409, "Email already registered")
    return await user_service.create(db, body)

app.include_router(router, prefix="/api/v1/users", tags=["users"])
```

### Step 7: Pagination and Filtering

**Offset-based:** `GET /api/v1/posts?page=2&limit=20` — returns `{ data, meta: { page, limit, total, totalPages } }`

**Cursor-based:** `GET /api/v1/posts?cursor=eyJpZCI6MTAwfQ&limit=20` — returns `{ data, meta: { nextCursor, hasMore } }`

Common query params: `sort=-createdAt,title`, `fields=id,title`, `search=keyword`, `status=active`, `createdAfter=2024-01-01`.

## Examples

### Example 1: Build a CRUD API for a project management app
**User prompt:** "Create a REST API with Express for managing projects and tasks. Include JWT authentication, input validation, and paginated list endpoints."

The agent will:
1. Set up Express 5 with `helmet`, `cors`, `compression`, and JSON body parsing
2. Define routes: `GET/POST /api/v1/projects`, `GET/PATCH/DELETE /api/v1/projects/:id`, `GET/POST /api/v1/projects/:id/tasks`
3. Create Zod schemas for `createProject` and `updateProject` input validation
4. Implement JWT authentication middleware that extracts the user from the Bearer token
5. Add paginated list endpoints returning `{ data, meta: { page, limit, total, totalPages } }`
6. Set up a global error handler returning `{ error: { code, message } }` with proper HTTP status codes

### Example 2: Add FastAPI endpoints with auto-generated docs
**User prompt:** "Create a FastAPI backend for a blog with users and posts. I want automatic OpenAPI documentation and Pydantic validation."

The agent will:
1. Define Pydantic models: `UserCreate`, `UserResponse`, `PostCreate`, `PostResponse`, and `PaginatedResponse[T]`
2. Create routers for `/api/v1/users` and `/api/v1/posts` with proper HTTP methods and status codes
3. Add dependency injection for database sessions and current user authentication
4. FastAPI automatically generates interactive docs at `/api/docs` (Swagger UI) and `/api/redoc`
5. Implement proper error handling with `HTTPException` using correct status codes (409 for duplicate email, 404 for missing resources)

## Guidelines

1. **Consistent response format** — always wrap in `{ data: ... }` or `{ error: ... }`
2. **Validate all input** — never trust request body, query, or params
3. **Use proper status codes** — 201 for creation, 204 for delete, 409 for conflicts
4. **Include Location header** — on 201 responses, point to the created resource
5. **Pagination by default** — never return unbounded collections
6. **Rate limit everything** — stricter limits on auth endpoints
7. **CORS configured explicitly** — never use `*` in production
8. **Idempotent PUT/DELETE** — calling twice produces the same result
9. **Error responses include machine-readable codes** — `VALIDATION_FAILED`, not just messages
10. **Version from day one** — `/api/v1/` costs nothing and saves future pain
11. **Express 4 vs 5** — Express 5 forwards rejected promises from async handlers to the error middleware; on Express 4 wrap handlers (or use `express-async-errors`) or `throw` inside `async` code will hang the request
12. **Validation status** — FastAPI returns 422 for invalid bodies by default; the Express examples use 400. Pick one convention per API and document it
13. **Passwords** — hash with Argon2id or bcrypt, never store or log them; `EmailStr` needs `pip install email-validator` (included in `fastapi[standard]`)
Pliki w paczce (2)
  • SKILL.md 10 KB
  • _scores.json 2 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · TerminalSkills/skills100Apache-2.0
envigoinnovations/subscriby-agentic-kit100MIT
claude-dev-suite/claude-dev-suite100MIT
vinnie357/claude-skills100MIT
G1Joshi/Agent-Skills100MIT

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

  • 100rest
    Projektuje REST API: OpenAPI 3.1, semantykę HTTP, zasoby, stronicowanie, cache, negocjację treści, CORS, limity i obsługę błędów.
  • 95api-design
    Opisuje wzorce projektowania REST API: nazwy zasobów, kody statusu, paginację, filtrowanie, odpowiedzi błędów, wersjonowanie i rate limiting dla API produkcyjnych.
  • 95api-design
    Opisuje wzorce projektowania REST API: nazwy zasobów, kody statusu, paginację, filtrowanie, odpowiedzi błędów, wersjonowanie i rate limiting dla API produkcyjnych.
  • 100koa
    Buduje REST API i usługi webowe w Koa, minimalistycznym frameworku Node.js od zespołu Express: routing, parsowanie body, CORS, obsługa błędów, własne middleware i migracja z Express lub Koa 2 do Koa 3.
  • 100rest-api-best-practices
    Doradza w projektowaniu i przeglądzie REST API: metody i kody HTTP, nazewnictwo URL, błędy, paginacja, wersjonowanie, uwierzytelnianie i rate limiting.
  • 100api-design
    Projektuje lub przegląda REST API: nazwy zasobów, kody statusu, stronicowanie, filtrowanie, błędy, wersjonowanie i limity.

Uwagi i zgłoszenia

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