What is the API Development skill for?

It orchestrates the full API lifecycle—design, build, test, document, and deploy—by coordinating specialized skills and commands into a seamless workflow.

What are the deliverables at each stage?

Deliverables include resource models, endpoint maps, OpenAPI spec, route files, type definitions, validation schemas, service modules, test suites, API docs, changelog, and deployment confirmation.

How is versioning handled?

Follow the api-versioning guidance: apply a version tag, maintain a changelog, and manage deprecation and migration as part of the deployment pipeline.

api-development

npx machina-cli add skill wpank/ai/api-development --openclaw

Files (1)

SKILL.md

7.7 KB

API Development

Orchestrate the full API development lifecycle by coordinating design, implementation, testing, and documentation into a single workflow.

When to Use This Skill

Building a new API from scratch
Adding endpoints to an existing API
Redesigning or refactoring an API
Planning API versioning and migration
Running a complete API development cycle (design → build → test → document → deploy)

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install api-development

Orchestration Flow

Follow these steps in order. Each step routes to the appropriate skill or tool.

1. Design the API

Load the api-design skill to establish resource models, URL structure, HTTP method semantics, error formats, and pagination strategy.

Deliverables: Resource list, endpoint map, request/response schemas, error format

2. Generate OpenAPI Spec

Produce a machine-readable OpenAPI 3.x specification from the design. Use the OpenAPI template in api-design/assets/openapi-template.yaml as a starting point.

Deliverables: openapi.yaml with all endpoints, schemas, auth schemes, and examples

3. Scaffold Endpoints

Generate route files, request/response types, and validation schemas for each endpoint. Group routes by resource.

Deliverables: Route files, type definitions, validation schemas per resource

4. Implement Business Logic

Write service-layer logic with input validation, authorization checks, database queries, and proper error propagation. Keep controllers thin — business logic lives in the service layer.

Deliverables: Service modules, repository layer, middleware (auth, rate limiting, CORS)

5. Test

Write tests at three levels:

Unit tests — service logic, validation, error handling
Integration tests — endpoint behavior with real DB
Contract tests — response shapes match OpenAPI spec

Deliverables: Test suite with coverage for happy paths, error cases, edge cases, and auth

6. Document

Generate human-readable API documentation with usage examples and SDK snippets. Ensure every endpoint has description, parameters, request/response examples, and error codes.

Deliverables: API docs, changelog, authentication guide

7. Version and Deploy

Apply a versioning strategy, tag the release, update changelogs, and deploy through the pipeline. Follow the api-versioning skill for deprecation and migration guidance.

Deliverables: Version tag, changelog entry, deployment confirmation

API Design Decision Table

Choose the right paradigm for your use case.

Criteria	REST	GraphQL	gRPC
Best for	CRUD-heavy public APIs	Complex relational data, client-driven queries	Internal microservices, high-throughput
Data fetching	Fixed response shape per endpoint	Client specifies exact fields	Strongly typed protobuf messages
Over/under-fetching	Common problem	Solved by design	Minimal — schema is explicit
Caching	Native HTTP caching (ETags, Cache-Control)	Requires custom caching	No built-in HTTP caching
Real-time	Polling or WebSockets	Subscriptions (built-in)	Bidirectional streaming
Tooling	Mature — OpenAPI, Postman, curl	Growing — Apollo, Relay, GraphiQL	Mature — protoc, grpcurl, Buf
Learning curve	Low	Medium	Medium-High
Versioning	URL or header versioning	Schema evolution with `@deprecated`	Package versioning in `.proto`

Rule of thumb: Default to REST for public APIs. Use GraphQL when clients need flexible queries across related data. Use gRPC for internal service-to-service communication.

API Checklist

Run through this checklist before marking any API work as complete.

Authentication & Authorization

Authentication mechanism chosen (JWT, OAuth2, API key)
Authorization rules enforced at every endpoint
Tokens validated and scoped correctly
Secrets stored securely (never in code or logs)

Rate Limiting

Rate limits configured per endpoint or consumer tier
RateLimit-* headers included in responses
429 Too Many Requests returned with Retry-After header
Rate limit strategy documented for consumers

Pagination

All collection endpoints paginated
Pagination style chosen (cursor-based or offset-based)
page_size bounded with a sensible maximum
Total count or hasNextPage indicator included

Filtering & Sorting

Filter parameters validated and sanitized
Sort fields allow-listed (no arbitrary column sorting)
Default sort order defined and documented

Error Handling

Consistent error response schema across all endpoints
Correct HTTP status codes (4xx for client, 5xx for server)
Validation errors return field-level detail
Internal errors never leak stack traces or sensitive data

Versioning

Versioning strategy selected and applied uniformly
Breaking vs non-breaking change policy documented
Deprecation timeline communicated via Sunset header

CORS

Allowed origins configured (no wildcard * in production with credentials)
Allowed methods and headers explicitly listed
Preflight (OPTIONS) requests handled correctly

Documentation

OpenAPI / Swagger spec generated and up to date
Every endpoint has description, parameters, and example responses
Authentication requirements documented
Error codes and meanings listed
Changelog maintained for each version

Security

Monitoring

Structured logging with request IDs
Error tracking configured (Sentry, Datadog, etc.)
Performance metrics collected (latency, error rate)
Health check endpoint available (/health)
Alerts configured for error rate spikes

Skill Routing Table

Need	Skill	Purpose
API design principles	`api-design`	Resource modeling, HTTP semantics, pagination, error formats
Versioning strategy	`api-versioning`	Version lifecycle, deprecation, migration patterns
Authentication	`auth-patterns`	JWT, OAuth2, sessions, RBAC, MFA
Error handling	`error-handling`	Error types, retry patterns, circuit breakers, HTTP errors
Rate limiting	`rate-limiting`	Algorithms, HTTP headers, tiered limits, distributed limiting
Caching	`caching`	Cache strategies, HTTP caching, invalidation, Redis patterns
Database migrations	`database-migrations`	Schema evolution, zero-downtime patterns, rollback strategies

NEVER Do

NEVER skip the design phase — jumping straight to code produces inconsistent APIs that are expensive to fix
NEVER expose database schema directly — API resources are not database tables; design around consumer use cases
NEVER ship without authentication — every production endpoint must have an auth strategy
NEVER return inconsistent error formats — every error response must follow the same schema
NEVER break a published API without a versioning plan — breaking changes require a new version, migration guide, and deprecation timeline
NEVER deploy without tests and documentation — untested APIs ship bugs, undocumented APIs frustrate developers

Source

git clone https://github.com/wpank/ai/blob/main/skills/api/api-development/SKILL.mdView on GitHub

Overview

API Development orchestrates the full lifecycle from design to documentation by coordinating specialized skills, agents, and commands into a single workflow. It guides you through design, OpenAPI spec generation, endpoint scaffolding, business logic implementation, testing, documentation, and deployment with versioning guidance.

How This Skill Works

It loads the api-design skill to establish resources, URL structure, and error formats. It then generates a machine-readable OpenAPI 3.x spec from the design, scaffolds routes and validation per resource, implements the service layer, and runs unit, integration, and contract tests before producing docs and applying a versioned deployment.

When to Use It

Building a new API from scratch
Adding endpoints to an existing API
Redesigning or refactoring an API
Planning API versioning and migration
Running a complete API development cycle (design → build → test → document → deploy)

Quick Start

Step 1: Design the API with the api-design skill to establish resources, URL structure, and error formats
Step 2: Generate the OpenAPI 3.x spec from the design and scaffold endpoints accordingly
Step 3: Implement service-layer logic, run unit/integration/contract tests, publish docs, and apply versioned deployment

Best Practices

Start with a formal API design using the api-design skill to define resources, URL structure, and error formats
Automatically generate an OpenAPI 3.x spec from the design to ensure consistency
Scaffold endpoints and validation schemas grouped by resource for clarity
Keep business logic in the service layer with thin controllers and proper error propagation
Adopt a three-layer test strategy (unit, integration, contract) and maintain up-to-date documentation and changelogs

Example Use Cases

Launching a new e-commerce product catalog API with complete OpenAPI spec and docs
Adding order and payment endpoints to an existing REST API and updating tests
Refactoring an API to improve pagination, error formats, and resource organization
Migrating an API to a versioned scheme with deprecation notices and migration guides
Automatically generating developer docs and SDK snippets after each design-build cycle

Frequently Asked Questions

Add this skill to your agents