# Design Consistent APIs with OpenAPI Templates

API teams often lose time resolving inconsistent routes, errors, versions, and documentation. This skill provides practical patterns, checklists, and templates for REST, GraphQL, gRPC, OpenAPI, and AsyncAPI work.

## Install

```bash
npx skillstore add ai agent hub/ariegoldkin-api-design-framework
```

## Metadata

- - Slug: ariegoldkin-api-design-framework
- - Version: 1.0.0
- - Author: AI Agent Hub
- - GitHub username: ArieGoldkin
- - License: MIT
- - Repository: https://github.com/ArieGoldkin/ai-agent-hub/tree/main/skills/api-design-framework
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: low
- - Risk factors: network
- - Quality score: 77
- - Quality tier: bronze
- - Public page: https://skillstore.pages.dev/skills/ariegoldkin-api-design-framework
- - Manifest: https://skillstore.pages.dev/api/skills/ariegoldkin-api-design-framework/manifest

## Capabilities

- Defines REST resource naming, HTTP method, status code, pagination, filtering, and versioning conventions.
- Provides GraphQL schema, query, mutation, connection, and error handling guidance.
- Provides gRPC proto structure, service design, message design, and status code guidance.
- Includes OpenAPI 3.1 and AsyncAPI 3.0 template files for API documentation.
- Includes a review checklist for API design, documentation, testing, performance, and launch readiness.
- Guides authentication, rate limiting, error response, webhook, and idempotency documentation patterns.

## Use Cases

- Create a New Public REST API: Use the conventions and OpenAPI template to define endpoints, errors, authentication, rate limits, and documentation before implementation.
- Review an API Contract Before Build: Use the checklist to compare a proposed contract against naming, versioning, error handling, performance, and launch requirements.
- Document Event-Driven Services: Use the AsyncAPI template to describe Kafka, RabbitMQ, WebSocket, or message-based channels, payloads, and security schemes.

## Prompt Templates

### Choose an API Style

```
Help me choose REST, GraphQL, or gRPC for this service. Ask for missing requirements, then recommend an API style with tradeoffs.
```

### Design REST Endpoints

```
Design REST endpoints for this resource model. Include routes, methods, status codes, pagination, filtering, errors, and versioning.
```

### Review an Existing Contract

```
Review this API contract against the API design checklist. Identify inconsistencies, missing documentation, security gaps, and launch blockers.
```

### Prepare Full API Documentation

```
Create an OpenAPI or AsyncAPI documentation plan for this service. Include schemas, operations, security schemes, examples, errors, and rollout notes.
```

## Limitations

- It provides guidance and templates, not a live API generator or validator.
- Template hostnames, support contacts, examples, and security schemes must be customized.
- It does not replace product requirements, architecture review, or security review.
- It does not run tests, inspect deployed services, or verify runtime behavior.

## Best Practices

- Start with requirements, users, data ownership, and API style before naming endpoints.
- Keep error formats, pagination, authentication, and versioning consistent across services.
- Replace all placeholder URLs, contacts, examples, and security schemes before publishing documentation.

## Anti Patterns

- Do not copy template endpoints or credentials into production without review.
- Do not mix naming conventions, status code meanings, or error formats across one API.
- Do not design breaking changes without versioning, deprecation notices, and migration guidance.

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-28T10:33:46.195\+00:00
- - Summary: Static analysis reported many high-risk patterns, but review found they are documentation examples, API route snippets, schema fields, and placeholder service URLs. No executable scripts, command execution, credential exfiltration, prompt injection, or malicious intent were found. The remaining low risk is that example URLs and auth placeholders must be customized before production use.

## Stats

- - Views: 295
- - Downloads: 5
- - Favorites: 1
- - Popularity score: 0