skills.rest
The13thNode
The13thNodeCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Designs REST and GraphQL API contracts with OpenAPI 3.0 specifications.

3|Updated Mar 26, 2026
Search Tags:#openapi#rest#graphql#swagger#webhooks#api-design#api-versioning
One-click install
npx skills add https://github.com/The13thNode/VibeCorp_PromptCEO --skill api-design-the13thnode
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/The13thNode/VibeCorp_PromptCEO/tree/main/skills/public/api-design
Command: npx skills add https://github.com/The13thNode/VibeCorp_PromptCEO --skill api-design-the13thnode

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill ensures API contracts are explicit and versioned before implementation to prevent frontend-backend mismatches, unstable public APIs, and undocumented integration points that break consumers.

Core Features & Use Cases

  • API Contracts & OpenAPI: Provide OpenAPI 3.0 templates, component schemas, and example paths to publish a machine-readable API contract for frontend and backend teams.
  • REST Principles & Response Standards: Recommend URL design, HTTP method usage, standard response envelopes, pagination meta, and a consistent error code mapping for reliable client behavior.
  • Webhooks, Security & Versioning: Specify webhook payload structure, HMAC signing and validation, retry policies, rate limiting headers, and clear rules for URL vs header versioning.
  • Use Case: Create a public developer API for users and posts with bearer authentication, standardized responses, documented error codes, and a webhook system for payment events to align engineering, QA, and documentation.

Quick Start

Design an OpenAPI v3 spec for a users and posts REST API with bearer token authentication, a standardized success/error payload, URL versioning, and a payment.succeeded webhook.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate an OpenAPI 3.0 spec for a REST API with bearer authentication?▼

To generate an OpenAPI 3.0 spec, define component schemas, example paths, and bearer token authentication to publish a machine-readable contract aligning frontend and backend teams.

What is the best way to structure webhook payloads with HMAC signing and retry policies?▼

Design webhook architecture by specifying payload structure, HMAC signing and validation, retry policies, and rate limiting headers to ensure reliable third-party event notifications.

How do I design REST API response envelopes and error code mappings?▼

Design REST APIs with URL design, HTTP method usage, standardized response envelopes, pagination meta, and a consistent error code mapping to ensure reliable client behavior.

When should I use URL versioning versus header versioning for API versioning strategy?▼

API versioning strategy requires clear rules for URL versus header versioning to prevent unstable public APIs and undocumented integration points that break consumers.

Does GraphQL schema design work with standardized response envelopes and error code mappings?▼

GraphQL schema design applies to frontend-backend and third-party integrations, complementing REST principles and OpenAPI generation for explicit, versioned API contracts.

Why do frontend and backend teams experience API integration mismatches?▼

Integration mismatches occur when API contracts are not explicit and versioned before implementation, causing unstable public APIs and undocumented integration points that break consumers.

Related Skills

Explore More Software Engineering Skills→
gridi-aigridi-ai
1

be-spec

Generate OpenAPI 3.0 specifications from tech specs for REST APIs.

Official
Advanced
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
secondskysecondsky
204

api-reference-documentation

Automate API documentation creation from OpenAPI 3.0 specifications.

Community
Advanced
Camilo8902Camilo8902

rest-to-graphql-migrator

Migrate REST APIs to GraphQL incrementally using schema stitching and REST data source wrappers.

Community
Advanced