skills.rest
Pyl-Tech
Pyl-TechOFFICIAL
Explore all skills by this author →
WebsiteGitHub

api-design

Enforce REST API endpoint design with checklists for contracts, errors, and versioning.

Updated Aug 27, 2026
Search Tags:#openapi#rest api#pagination#api versioning#endpoint design#http status codes#error envelope
One-click install
npx skills add https://github.com/Pyl-Tech/stream-coding --skill api-design-pyl-tech
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/Pyl-Tech/stream-coding/tree/main/.agents/skills/api-design
Command: npx skills add https://github.com/Pyl-Tech/stream-coding --skill api-design-pyl-tech

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill prevents broken REST endpoints by enforcing consistent endpoint structure, validated request/response contracts, and safe, non-leaky error handling before anything goes live.

Core Features & Use Cases

  • Endpoint checklist for release readiness: Ensures correct resource naming, HTTP methods, status codes, schema-validated inputs, and consistent response behavior.
  • Strict error envelope standardization: Forces a predictable error structure with machine-readable codes and safe, optional details.
  • Versioning, pagination, and migration guardrails: Requires pagination support, limits active API versions, and uses Sunset headers with planned deprecation to avoid breaking clients.
  • Rationalization prevention: Blocks common excuses that lead to unverified behavior (e.g., “document later,” “no contracts for internal,” “we’ll version later”).
  • Red-flag detection for API design drift: Highlights issues like missing pagination, breaking changes without versioning, and incorrect PUT/PATCH usage.

Quick Start

Review the proposed endpoint and verify it satisfies the endpoint checklist, error envelope format, and versioning/migration rules for your API changes.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design REST API endpoints to avoid breaking existing clients?▼

To design REST API endpoints that avoid breaking clients, enforce schema-validated inputs, consistent HTTP status codes, and API versioning with Sunset-based deprecation discipline. This ensures predictable contract changes and prevents client-breaking behavior.

What is the best way to standardize error envelopes in a REST API?▼

Standardizing REST API error envelopes requires a predictable structure with machine-readable codes and safe, optional details. This strict error envelope standardization forces consistent error handling and prevents sensitive data leakage in API responses.

How do I plan API versioning and migration for REST endpoints?▼

REST API versioning and migration requires limiting active API versions and using Sunset headers with planned deprecation. This migration guardrail prevents breaking clients by enforcing a disciplined deprecation process for outdated endpoints.

When do I need pagination support in my REST API design?▼

Pagination support is needed in REST API design whenever endpoints return collection resources. Detecting missing pagination is a red flag for API design drift, and enforcing pagination limits prevents unbounded payload responses.

Does incorrect PUT or PATCH usage count as REST API design drift?▼

Incorrect PUT or PATCH usage is a red-flag indicator of REST API design drift. Reviewing proposed endpoints against an endpoint checklist catches incorrect HTTP method usage and ensures safe, non-leaking response behavior.

Can I skip request contracts for internal REST API endpoints?▼

Skipping request contracts for internal REST API endpoints is blocked by rationalization prevention. Internal endpoints still require schema-validated inputs and consistent response behavior to ensure reliable REST API contracts before going live.

Related Skills

Explore More Software Engineering Skills→
ConradmakerConradmaker

be-api-design

Design REST API contracts with OpenAPI 3.1 schemas and RFC 7807 errors.

Community
Advanced
nikblanchetnikblanchet

handle-deprecation-warnings

Identify deprecation warnings and migrate code to recommended APIs.

Community
Basic
zdanovichnickzdanovichnick
4

aspnet-api-patterns

Define ASP.NET Core API patterns for controllers, minimal APIs, middleware, and JWT authentication.

Community
Basic
gabriellpequenogabriellpequeno
8

api-patterns

Define and enforce API design patterns across REST, GraphQL, and tRPC implementations.

Community
Intermediate