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.
- Autor
- TerminalSkills ↗
- Repozytorium
- skills ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 25.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.
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
- Overview
- Instructions
- Examples
- Guidelines
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
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · TerminalSkills/skills | 100 | Apache-2.0 |
| envigoinnovations/subscriby-agentic-kit | 100 | MIT |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| vinnie357/claude-skills | 100 | MIT |
| G1Joshi/Agent-Skills | 100 | MIT |
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.