# Flask API Design

> Building clean, RESTful APIs with Marshmallow for serialization and OpenAPI documentation.

- Skill: `jcorpac/flask-api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jcorpac/flask-api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jcorpac/flask-api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: jcorpac (https://skillmd.com/u/jcorpac)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jcorpac/flask-api-design

---


# Flask API Design

APIs should be self-documenting, consistent, and easy to consume.

## Serialization (Marshmallow)
- **Schemas**: Transforming complex objects to/from primitive Python types.
- **Validation**: Enforcing data constraints at the API layer.

## RESTful Routing
- **Nouns not Verbs**: `/users/1` instead of `/getUser/1`.
- **HTTP Methods**: GET (read), POST (create), PUT/PATCH (update), DELETE (remove).

## Documentation
Use **Flask-Smorest** or **Flasgger** to automatically generate Swagger/OpenAPI UI for your endpoints.

## Best Practices
- **Status Codes**: Return appropriate codes (e.g., `201 Created`, `404 Not Found`, `422 Unprocessable Entity`).
- **Versioning**: Prefix routes with `/api/v1/`.