api-designer-skill_skill

This skill designs REST and GraphQL APIs with OpenAPI 3.1, HATEOAS, pagination, and versioning to deliver scalable, developer-friendly interfaces.

Python

21

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill 404kidwiz/claude-supercode-skills --skill api-designer-skill

SKILL.md13.6 KB

Overview

This skill provides hands-on API architecture guidance for REST and GraphQL systems with emphasis on OpenAPI 3.1, HATEOAS, pagination, and versioning strategies. It helps teams produce consistent, discoverable, and well-documented APIs that scale and are easy for client developers to consume. The focus is practical: resource modeling, error standardization, pagination patterns, and versioning approaches.

How this skill works

I analyze requirements and propose resource models, URL structures, and operation semantics (CRUD, nested resources, links). I produce OpenAPI 3.1 specifications, example schemas, standardized error formats, and pagination/linking patterns (cursor, limit, HATEOAS links). I also advise on versioning (URL, header, content negotiation), security handoffs, and documentation generation and deployment.

When to use it

Designing a new RESTful or GraphQL API from product requirements
Authoring or refining OpenAPI 3.1 specs for documentation and codegen
Establishing consistent error response formats and HTTP status usage
Choosing and implementing pagination, filtering, and sorting for large datasets
Defining API versioning strategy and migration paths

Best practices

Model resources around nouns and relationships, not RPC verbs
Standardize a single error envelope with machine codes and field-level details
Prefer cursor-based pagination for large or changing datasets; include meta and HATEOAS links
Keep versioning explicit (URL for public stability, header/content negotiation for evolution)
Publish OpenAPI 3.1 specs and produce generated client types and interactive docs

Example use cases

Designing an e-commerce product catalog API with paginated listings and nested reviews
Converting ad-hoc endpoints into a single OpenAPI 3.1 spec for frontend and SDK generation
Implementing HATEOAS links so clients can discover next/prev pages and related resources
Defining error contracts so frontend teams can implement unified client-side handling
Choosing a versioning approach and migration plan for breaking API changes

FAQ

Use cursor-based pagination for large, mutable datasets; include limit, opaque cursor, total hints in meta, and next/prev links for HATEOAS.

When should I use URL versioning vs header versioning?

Use URL versioning for clear public stability guarantees and simpler routing; use header/content negotiation for smoother evolution when breaking changes are rare and you want cleaner URLs.