moai-ref-api-patterns

Provides REST and GraphQL API design conventions, error handling, and validation patterns for backend development.

Updated Jul 24, 2026
One-click install
npx skills add https://github.com/jjjh7401/AI-Lighting_Console --skill moai-ref-api-patterns-jjjh7401
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: moai-ref-api-patterns
Source: https://github.com/jjjh7401/AI-Lighting_Console/tree/main/.claude/skills/moai-ref-api-patterns
Command: npx skills add https://github.com/jjjh7401/AI-Lighting_Console --skill moai-ref-api-patterns-jjjh7401

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Backend developers often ship APIs with inconsistent naming, ad-hoc error formats, missing pagination, and unplanned versioning, which creates maintenance burden and breaks client integrations. This Skill supplies a consolidated reference of production-grade API design patterns so endpoints, error responses, and validation follow consistent conventions. ## Core Features & Use Cases - RESTful Design Conventions: Resource naming, HTTP method mapping, status code selection, filtering, sorting, and URL versioning rules in lookup-table form. - Error & Pagination Standards: Standardized error response JSON with machine-readable codes and request IDs, plus offset and cursor-based pagination patterns. - Validation & Rate Limiting Checklists: Input validation methods (schema, regex, range, enum) mapped to tools like Zod, Joi, and pydantic, with rate limit targets and headers. - Use Case: When reviewing a new /users endpoint, an agent can verify naming conventions, confirm 422 responses include field-level error details, and check that list endpoints implement pagination before merge. ## Quick Start Ask the agent to review your API endpoint design against REST conventions for naming, status codes, error format, and pagination.

Frequently Asked Questions about moai-ref-api-patterns

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

FAQPage Schema
How do I design RESTful API endpoints with consistent naming?▼

Use plural lowercase nouns in kebab-case for resources, such as /api/v1/user-profiles, and map HTTP methods to operations: POST creates, PUT replaces, PATCH partially updates, DELETE removes. Keep nested resources at most two levels deep.

What HTTP status codes should API endpoints return?▼

Return 200 for successful reads and updates, 201 for resource creation, 204 for deletes without a body, 400 for validation failures, 401/403 for auth issues, 404 for missing resources, 409 for conflicts, and 429 when rate limits are exceeded.

How should API error responses be formatted?▼

Use a consistent JSON envelope with a machine-readable error code, human-readable message, field-level details array, and a request_id for traceability. Never expose stack traces, and never reveal which credential failed during login.

When should I use cursor-based vs offset pagination?▼

Use offset pagination with page, limit, and total fields for typical datasets. Use cursor-based pagination with an opaque next cursor for large datasets where offset performance degrades or data changes frequently during iteration.

What API changes require a version bump?▼

Breaking changes require a version bump: removing or renaming fields, changing field types, removing endpoints, or changing authentication. Adding optional fields, new endpoints, or new query parameters is non-breaking and needs no bump.

When is this API patterns reference not applicable?▼

It does not cover frontend development, DevOps, database schema design, or security audits. It is a design-convention reference for backend API work, not an implementation framework or a substitute for threat modeling.