api-rest-designer_skill

This skill designs production-ready RESTful APIs with OpenAPI 3.1/3.2, including resource modeling, pagination, HATEOAS, and OWASP security.

Python

5

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 williamzujkowski/cognitive-toolworks --skill api-rest-designer

SKILL.md30.7 KB

Overview

This skill helps design production-ready RESTful APIs using OpenAPI 3.1/3.2, resource modeling, HTTP semantics, versioning, pagination, HATEOAS, and OWASP API Security mitigations. It produces concise API designs, OpenAPI specs, and practical guidance for migrating to Richardson Level 2/3 APIs.

How this skill works

Provide a domain model and use cases; the skill validates entity keys, relationships, and HTTP-method mappings, computes a timestamp anchor for the design, and selects patterns based on maturity targets. It can generate single-resource CRUD specs, multi-resource APIs with versioning/pagination/security, or HATEOAS-enabled Level 3 designs including webhooks, bulk operations, and RFC 7807 error structures.

When to use it

Design a new REST API from scratch with clear resource URIs and HTTP semantics
Generate OpenAPI 3.1/3.2 specs with JSON Schema, webhooks, and security schemes
Migrate RPC/SOAP or Level 0/1 APIs to proper RESTful semantics (Level 2+)
Add versioning, pagination, filtering, or move from offset to cursor/keyset paging
Implement HATEOAS for discoverable APIs or to expose dynamic client actions
Apply OWASP API Security Top 10 mitigations and prepare gateway integration

Best practices

Model resources with primary keys and explicit relationships before designing URIs
Prefer flat URIs for queryable collections; use nested URIs only when access is always through the parent
Default to URI versioning unless gateway or client constraints require header/media-type versioning
Choose pagination strategy per scale: offset for simplicity, cursor/keyset for performance
Enforce OWASP mitigations: authorization checks, token validation, rate limiting, input validation, and least-privilege responses
Use ETag/If-None-Match, RFC 7807 Problem Details, and standardized rate-limit headers for robust client behavior

Example use cases

Quick CRUD API for a single resource: generate OpenAPI 3.1 spec for Users with standard pagination and status codes
Multi-resource e-commerce API: Users, Orders, Products with URI versioning, cursor pagination, filtering, and JWT security
HATEOAS-enabled order service: resources include _links for discoverability and action affordances based on status
Gateway-integrated deployment: spec includes securitySchemes and recommends rate limits and Idempotency-Key usage
Migration plan: move from offset-based paging to cursor/keyset with a backward-compatible pagination transition

FAQ

You must supply a domain_model with at least one entity (with primary keys) and at least one use_case mapped to HTTP semantics.

Which pagination should I pick for large datasets?

Use cursor or keyset pagination for large or real-time datasets; offset is fine for small/admin interfaces or simple pagination.

Can this produce HATEOAS and webhooks in OpenAPI?

Yes — the skill can generate Level 3 responses with _links, define webhooks in OpenAPI 3.1, and include bulk endpoints and idempotency support.