rest-api-guidelines
REST API Guidelines
Apply consistent default decisions for HTTP+JSON REST APIs. Favor predictability, interoperability, retry safety, and long-term compatibility over stylistic purity.
Overview
Use this skill for three kinds of work:
- Design a new REST API or refine an existing design.
- Review an API, OpenAPI spec, or endpoint proposal for rule violations and compatibility risks.
- Draft endpoint contracts with example request and response shapes.
Workflow
- Classify the request as
design,review, ordraft. - Start from the default decisions in this file unless the user or existing platform conventions require otherwise.
- Read only the reference files needed for the task.
- State any deviation from the defaults explicitly and explain why it is justified.
- Keep the contract internally consistent across naming, methods, status codes, pagination, error format, and versioning.
More from wibaek/skills
python-starter
Automatically configures formatter and linter settings when initializing Python projects. Installs ruff by default and uses pyproject.toml for configuration. Detects or asks the user about venv/poetry/uv environments and installs as dev dependencies. Optionally configures pre-commit and ty. Suggests VSCode workspace settings when using VSCode. Use this skill when starting Python projects ("Start a Python project", "Create a FastAPI project", "Create a data analysis Python project", etc.).
8ts-starter
Configure TypeScript project tooling for existing Node or frontend projects without app scaffolding. Use for TS starter setup, TS lint/format/test setup, Node TypeScript starter, or Vite TypeScript config requests.
6github-pr-writer
Draft GitHub pull request titles and structured PR bodies from branch history, diffs, and validation results. Use when Codex needs to write a PR description, summarize a branch for review, choose a base branch, prepare `gh pr create`, or open a pull request that follows the repository template.
2git-commit-writer
Draft Conventional Commit messages and execute a safe git commit workflow from staged or changed files. Use when Codex needs to create a commit, suggest a commit message, inspect git diff before committing, split changes into sensible commits, or run `git commit` without including unrelated work.
2