skills.rest
shwilliamson
shwilliamsonCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Design RESTful APIs with conventions for URLs, methods, versioning, and errors.

5|1|Updated Jan 2, 2026
Search Tags:#design#versioning#documentation#API#REST#error-handling
One-click install
npx skills add https://github.com/shwilliamson/automatasaurus --skill api-design-shwilliamson
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/shwilliamson/automatasaurus/tree/main/template/skills/api-design
Command: npx skills add https://github.com/shwilliamson/automatasaurus --skill api-design-shwilliamson

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps teams design consistent RESTful APIs by providing standard conventions, patterns, and documentation practices to improve interoperability and maintainability.

Core Features & Use Cases

  • Resource-oriented URLs and clear routing for API endpoints.
  • Consistent HTTP method semantics, status codes, and error handling.
  • Versioning and documentation guidance to support stable contracts over time.
  • Use Case: When designing a new API or reviewing an existing contract, apply these guidelines to ensure consistency and clarity.

Quick Start

To begin, outline your API resources and endpoints, then apply the REST design conventions to verify URL structure, method usage, error handling, and versioning.

Frequently Asked Questions about api-design

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

FAQPage Schema
What are the standard REST API design conventions for resource URLs and HTTP methods?▼

REST API design conventions enforce resource-oriented URLs and clear routing by applying consistent HTTP method semantics. This ensures predictable endpoint behavior, clear routing structures, and maintainable API contracts for interoperability.

How do I structure machine-readable error handling and status codes for a REST API?▼

Structure REST API error handling by applying consistent HTTP status codes and machine-readable error formats. This enforces predictable semantics, guiding clear API contracts and improving overall system maintainability and interoperability.

What is the best way to handle API versioning and documentation for stable contracts?▼

The best way to handle API versioning and documentation is applying standard conventions to support stable contracts over time. This guides clear routing, predictable semantics, and machine-readable errors for long-term maintainability.

How do I design a scalable REST API from scratch?▼

Design a scalable REST API by outlining your resources and endpoints, then applying standard conventions to verify URL structure, method usage, error handling, and versioning. This ensures consistency and clarity across the API.

Can I use these REST API design patterns to review an existing API contract?▼

Yes, you can use these REST API design patterns to review an existing contract. Applying the guidelines to URL structure, method usage, error handling, and versioning ensures consistency and clarity when validating current API implementations.

Related Skills

Explore More Software Engineering Skills→
sunnypatneedisunnypatneedi
11

api-design

Design RESTful API endpoints with OpenAPI documentation generation.

Community
Intermediate
curiositechcuriositech
181

openapi-spec-writer

Generate OpenAPI 3.0/3.1 YAML or JSON specifications for REST APIs.

Official
Advanced
GaryOcean428GaryOcean428

api-design-validation

Validate REST API endpoint naming, HTTP methods, and status codes.

Community
Intermediate
NovusAevumNovusAevum
1

api-design-principles

Guide REST and GraphQL API design with resource-oriented patterns and versioning strategies.

Community
Intermediate