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:

1. Design a new REST API or refine an existing design.
2. Review an API, OpenAPI spec, or endpoint proposal for rule violations and compatibility risks.
3. Draft endpoint contracts with example request and response shapes.

Workflow

1. Classify the request as design, review, or draft.
2. Start from the default decisions in this file unless the user or existing platform conventions require otherwise.
3. Read only the reference files needed for the task.
4. State any deviation from the defaults explicitly and explain why it is justified.
5. Keep the contract internally consistent across naming, methods, status codes, pagination, error format, and versioning.