Index of every page on this site: llms.txt
All skills
asyrafhussin avatar

/api-design-patterns

@1aa0ff7
Run it yourself

RESTful API design, error handling, versioning, and best practices. Use when designing APIs, reviewing endpoints, implementing error responses, or setting up API structure. Triggers on "design API", "review API", "REST best practices", or "API patterns".

Use this Skill: https://skilld.dev/gh/asyrafhussin/agent-skills/api-design-patterns

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈69 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈100k more on demand in 43 files.

Description uses 3.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈276 characters, or 3.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

API Design Patterns

RESTful API design principles for building consistent, developer-friendly APIs. Contains 38 rules across 7 categories covering resource design, error handling, security, pagination, versioning, response format, and documentation.

Metadata

  • Version: 2.0.0
  • Rule Count: 38 rules across 7 categories
  • License: MIT

When to Apply

Reference these guidelines when:

  • Designing new API endpoints
  • Reviewing existing API structure
  • Implementing error handling and validation
  • Setting up pagination, filtering, and sorting
  • Planning API versioning strategy
  • Configuring API security (auth, CORS, rate limiting)
  • Writing API documentation (OpenAPI/Swagger)

Rule Categories by Priority

Priority Category Impact Prefix
1 Resource Design CRITICAL rest-
2 Error Handling CRITICAL error-
3 Security CRITICAL sec-
4 Pagination & Filtering HIGH page-, filter-, sort-
5 Versioning HIGH ver-
6 Response Format MEDIUM resp-
7 Documentation MEDIUM doc-

Quick Reference

1. Resource Design (CRITICAL)

  • rest-nouns-not-verbs - Use nouns for endpoints, not verbs
  • rest-plural-resources - Use plural resource names
  • rest-http-methods - Correct HTTP method usage (GET, POST, PUT, PATCH, DELETE)
  • rest-nested-resources - Proper resource nesting (max 2 levels)
  • rest-status-codes - Appropriate HTTP status codes
  • rest-idempotency - Idempotent operations with idempotency keys
  • rest-hateoas - Hypermedia links for discoverability
  • rest-resource-actions - Non-CRUD actions as sub-resources

2. Error Handling (CRITICAL)

  • error-consistent-format - Consistent error response structure
  • error-meaningful-messages - Helpful, actionable error messages
  • error-validation-details - Field-level validation errors
  • error-error-codes - Machine-readable error codes
  • error-no-stack-traces - Never expose stack traces in production
  • error-request-id - Include request IDs for debugging

3. Security (CRITICAL)

  • sec-authentication - Proper auth implementation (OAuth2/JWT)
  • sec-authorization - Resource-level permissions (RBAC)
  • sec-rate-limiting - Prevent abuse with rate limiting
  • sec-input-validation - Validate and sanitize all input
  • sec-cors-config - CORS configuration with whitelists
  • sec-https-only - Enforce HTTPS for all traffic
  • sec-sensitive-data - Protect passwords, tokens, PII

4. Pagination & Filtering (HIGH)

  • page-cursor-based - Cursor pagination for large datasets
  • page-offset-based - Offset pagination for simple cases
  • page-consistent-params - Consistent parameter naming
  • page-metadata - Include pagination metadata in responses
  • filter-query-params - Filter via query parameters
  • sort-flexible - Flexible sorting with - prefix for descending

5. Versioning (HIGH)

  • ver-url-path - Version in URL path (/api/v1/)
  • ver-header-based - Version via Accept header
  • ver-backward-compatible - Maintain backward compatibility
  • ver-deprecation - Deprecation strategy with Sunset header

6. Response Format (MEDIUM)

  • resp-consistent-structure - Consistent response envelope
  • resp-json-conventions - JSON naming conventions
  • resp-partial-responses - Field selection (sparse fieldsets)
  • resp-compression - Response compression (gzip/Brotli)

7. Documentation (MEDIUM)

  • doc-openapi - OpenAPI/Swagger specification
  • doc-examples - Request/response examples
  • doc-changelog - API changelog

Essential Guidelines

Resource Naming

# ❌ Verbs in URLs
GET    /getUsers
POST   /createUser

# ✅ Nouns with HTTP methods
GET    /users          # List users
POST   /users          # Create user
GET    /users/123      # Get user
PUT    /users/123      # Update user (full)
PATCH  /users/123      # Update user (partial)
DELETE /users/123      # Delete user

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Please provide a valid email address"
      }
    ],
    "request_id": "req_abc123"
  }
}

Pagination

{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total_pages": 10,
    "total_count": 195
  },
  "links": {
    "first": "/users?page=1&per_page=20",
    "prev": "/users?page=1&per_page=20",
    "next": "/users?page=3&per_page=20",
    "last": "/users?page=10&per_page=20"
  }
}

Rate Limiting Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1640995200

How to Use

Read individual rule files for detailed explanations:

rules/rest-http-methods.md
rules/error-consistent-format.md
rules/page-cursor-based.md
rules/sec-authentication.md
rules/ver-url-path.md
rules/doc-openapi.md

References

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill is a comprehensive documentation library for RESTful API design patterns. It provides best practices for resource design, error handling, security, and documentation. The skill contains no executable code, malicious instructions, or hidden functionality, and its references are restricted to well-known technical documentation sources.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    4/28 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 1aa0ff7. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago
metadata
{
  "author": "agent-skills",
  "version": "2.0.0"
}

README badge

README badge for asyrafhussin/agent-skills/api-design-patterns