moai-ref-api-patterns

REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development. Agent-extending skill that amplifies backend domain work (spawned via Agent(general-purpose) with backend instructions) with production-grade API patterns. Use when designing APIs, implementing endpoints, or reviewing backend code. NOT for: frontend development, DevOps, database schema design, security audits.

Jump to install

Repository: modu-ai/moai-adk
Last source activity: July 2, 2026 at 02:40
Detected SKILL.md language: English
Stars: 1,174
Forks: 219

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/modu-ai/moai-adk --skill moai-ref-api-patterns

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

moai-harness-learner

Harness learning subsystem coordinator. Produces Tier 4 auto-update proposal payloads consumed by the orchestrator (which surfaces them via AskUserQuestion) and orchestrates Apply/Rollback flows. Triggers when harness learning proposals are pending or learning lifecycle management is needed.

2026-08-16

moai-meta-harness

DEPRECATED — legacy 7-Phase meta-harness. Redirects to the v4 harness Builder (/moai:harness <natural-language request>) which replaces the static 7-Phase workflow with an orchestrator-direct 4-phase Builder (ANALYZE / PLAN / GENERATE / ACTIVATE) + a manifest-driven dynamic-workflow Runner. Retained as the redirect source for backward-compat invocation paths; the 7-Phase body below is preserved as historical reference, NOT for new harness creation.

2026-08-16

moai

MoAI unified orchestrator for autonomous development. Routes natural language or subcommands (plan, run, sync, project, fix, loop, mx, feedback, review, clean, codemaps, gate, e2e, harness, goal, todo) to specialized agents.

2026-08-16

View all from this repository

name	moai-ref-api-patterns
description	REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development. Agent-extending skill that amplifies backend domain work (spawned via Agent(general-purpose) with backend instructions) with production-grade API patterns. Use when designing APIs, implementing endpoints, or reviewing backend code. NOT for: frontend development, DevOps, database schema design, security audits.
when_to_use	Use for REST/GraphQL API design patterns: endpoint and route design, handler structure, request/response conventions, error handling, and input validation. Amplifies backend domain work (Agent(general-purpose) with backend instructions) with production-grade API patterns.
user-invocable	false
metadata	{"version":"1.0.0","category":"domain","status":"active","updated":"2026-03-30","tags":"api, rest, graphql, patterns, backend, reference"}
progressive_disclosure	{"enabled":true,"level1_tokens":100,"level2_tokens":3000}

API Patterns Reference

Target Spawn

Backend domain work spawned via with backend instructions - Applies these patterns directly to API implementation and review.

Principle	Convention	Example
Resource Naming	Plural nouns, lowercase, kebab-case	`/api/v1/user-profiles`
Collection	GET returns array with pagination	`GET /users?page=1&limit=20`
Single Resource	GET returns object	`GET /users/{id}`
Create	POST to collection	`POST /users`
Update (full)	PUT to resource	`PUT /users/{id}`
Update (partial)	PATCH to resource	`PATCH /users/{id}`
Delete	DELETE to resource	`DELETE /users/{id}`
Nested Resources	Max 2 levels deep	`/users/{id}/posts`
Filtering	Query params	`?status=active&role=admin`
Sorting	Sort param	`?sort=-created_at,name`
Versioning	URL prefix	`/api/v1/`, `/api/v2/`

Category	Code	When to Use
Success	200 OK	Successful GET, PUT, PATCH, DELETE
Success	201 Created	Successful POST (resource created)
Success	204 No Content	Successful DELETE (no body)
Client Error	400 Bad Request	Malformed request, validation failure
Client Error	401 Unauthorized	Missing or invalid authentication
Client Error	403 Forbidden	Authenticated but not authorized
Client Error	404 Not Found	Resource does not exist
Client Error	409 Conflict	Resource state conflict (duplicate)
Client Error	422 Unprocessable	Valid syntax but semantic error
Client Error	429 Too Many	Rate limit exceeded
Server Error	500 Internal	Unexpected server error
Server Error	503 Service Unavailable	Maintenance or overload

Validation	Method	Tool
Type validation	Schema validation	Zod, Joi, pydantic, Go validator
Length limits	Min/max constraints	Schema min/max
Pattern matching	Regex	Email, URL, phone patterns
Range validation	Number/date bounds	min/max values
Enumeration	Allowed values	enum types
SQL Injection	Parameterized queries	ORM (Prisma, GORM, SQLAlchemy)
XSS	HTML escaping	Template engines, DOMPurify
Path Traversal	Path normalization	filepath.Clean + whitelist

Target	Limit	Key
Auth endpoints	5 req/min	IP
General API	100 req/min	User token
File upload	10 req/hour	User token
Public API	30 req/min	IP

Strategy	Use Case	Example
URL prefix	Most APIs	`/api/v1/users`
Header	Internal APIs	`Accept: application/vnd.api+json; version=2`
Query param	Simple APIs	`/users?version=2`

moai-ref-api-patterns

Install options

Review the source files

API Patterns Reference

Target Spawn

API Patterns Reference

Target Spawn

RESTful API Design Conventions

HTTP Status Code Guide

Error Response Format

Pagination Pattern

Input Validation Checklist

Rate Limiting Strategy

API Versioning Strategy

Common Rationalizations

Red Flags

Verification

Rationalization	Reality
"REST naming conventions are just aesthetics"	Consistent resource naming is how clients discover and predict endpoints. Inconsistency multiplies documentation burden.
"GraphQL solves over-fetching, so I do not need to design response shapes"	GraphQL shifts complexity to the resolver layer. Poorly designed schemas create N+1 queries and authorization gaps.
"Error codes are internal details, clients just need the message"	Clients need machine-readable error codes for programmatic handling. Messages are for humans, codes are for code.
"PATCH and PUT are interchangeable"	PATCH applies partial updates; PUT replaces the entire resource. Using them incorrectly breaks idempotency expectations.
"I will version the API when it becomes necessary"	Versioning after breaking changes forces emergency migrations. Plan versioning from the first release.

moai-ref-api-patterns

Source facts

Install options

Review the source files

More from this repository

More from this repository

API Patterns Reference

Target Spawn

API Patterns Reference

Target Spawn

RESTful API Design Conventions

HTTP Status Code Guide

Error Response Format

Pagination Pattern

Input Validation Checklist

Rate Limiting Strategy

API Versioning Strategy

Common Rationalizations

Red Flags

Verification