What is the api-development skill?

A meta-skill that orchestrates the full API lifecycle—from design through documentation—by coordinating specialized skills, agents, and commands into a seamless build workflow.

How does the orchestration flow work?

It follows seven steps: design with api-design, generate OpenAPI spec, scaffold endpoints, implement business logic, test (unit, integration, contract), document, and finally version and deploy.

How does versioning and deployment work?

A versioning strategy is applied, a release tag and changelog are created, and deployment proceeds through the pipeline, guided by api-versioning for deprecation and migration.

api-development

Scanned

@wpank

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

Files (1)

SKILL.md

7.6 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)

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://clawhub.ai/wpank/api-developmentView on GitHub

Overview

api-development is a meta-skill that orchestrates the full API lifecycle—from design to documentation—by coordinating specialized skills, agents, and commands into a seamless build workflow. It guides teams from API design through OpenAPI generation, endpoint scaffolding, business-logic implementation, testing, documentation, and deployment for cohesive API projects.

How This Skill Works

It follows a fixed orchestration flow: design the API with the api-design skill to establish resources, URL structure, methods, errors, and pagination; generate an OpenAPI 3.x spec from that design using the provided template; scaffold routes, types, and validation; implement the business logic in a thin controller layer with a robust service layer; and then test (unit, integration, contract), document with usage examples, and apply versioning and deployment. Each step yields concrete deliverables (openapi.yaml, route files, tests, docs) and is routed to the appropriate skill or tool.

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 resource models, URL structure, HTTP methods, error formats, and pagination strategy.
Step 2: Generate the OpenAPI 3.x spec from the design using the template at api-design/assets/openapi-template.yaml.
Step 3: Scaffold endpoints, implement the service layer, add tests, and generate documentation; then perform versioning and deployment.

Best Practices

Start with API design to align on resources, URL structure, methods, errors, and pagination.
Reuse the OpenAPI template and keep documentation in sync with design.
Keep controllers thin; place business logic in the service layer.
Write unit, integration, and contract tests with OpenAPI-aligned expectations.
Plan versioning, changelogs, and deployment early, following api-versioning guidance.

Example Use Cases

Designing a new REST API for a fintech platform from scratch
Adding a new endpoint to an existing e-commerce API
Refactoring an API to support a breaking change with a documented migration path
Versioning an API and coordinating deployment across services
Automating an end-to-end pipeline from design through deployment in a microservices project

Frequently Asked Questions

Add this skill to your agents