Verified:GitHub

rest-api-design

Design, review, and document HTTP REST API endpoints with schemas and RFC 7807 errors.

3|1|Updated Mar 11, 2026

Search Tags:#documentation #api design #rest #http #endpoints #contracts

One-click install

npx skills add https://github.com/jon23d/skillz --skill rest-api-design-jon23d

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: rest-api-design
Source: https://github.com/jon23d/skillz/tree/main/skills/rest-api-design
Command: npx skills add https://github.com/jon23d/skillz --skill rest-api-design-jon23d

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps developers and architects design, review, and document robust and user-friendly HTTP REST API endpoints, ensuring consistency and adherence to best practices.

Core Features & Use Cases

Resource-Oriented Design: Guides the creation of API endpoints using nouns and plural roots.
HTTP Method Semantics: Clarifies the appropriate use of GET, POST, PUT, PATCH, and DELETE.
Nesting and Relationships: Provides rules for structuring related resources.
Naming Conventions: Defines standards for URLs, query parameters, and JSON payloads (camelCase).
Versioning Strategies: Recommends URL-based versioning.
Standard Formats: Includes examples for pagination and error responses (RFC 7807).
Use Case: When designing a new /users endpoint, this skill ensures you use GET /users for listing, POST /users for creation, and GET /users/{id} for retrieval, following all naming and formatting guidelines.

Quick Start

Use the rest-api-design skill to create a GET endpoint for retrieving a list of products, following all best practices.

Frequently Asked Questions about rest-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I design REST API endpoints and resources correctly?▼

How should I structure JSON payloads, naming conventions, and versioning for HTTP APIs?

How should I structure JSON payloads, naming conventions, and versioning for HTTP APIs?▼

What is the standard format for REST API pagination and error responses?

What is the standard format for REST API pagination and error responses?▼

When should I use nesting and relationships in REST API resource design?

When should I use nesting and relationships in REST API resource design?▼

What are common mistakes to avoid when reviewing HTTP REST API contracts?

What are common mistakes to avoid when reviewing HTTP REST API contracts?▼

Common mistakes to avoid when reviewing HTTP REST API contracts include misusing HTTP verbs, improper URL naming, and ignoring standard formats. Reviewing endpoints against these guidelines prevents inconsistent resource orientation and broken API schemas.