api-designer

Designs REST and GraphQL APIs with OpenAPI 3.1 specifications and validation.

Updated Feb 24, 2026
One-click install
npx skills add https://github.com/marketiv-id/marketiv-web --skill api-designer-marketiv-id
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-designer
Source: https://github.com/marketiv-id/marketiv-web/tree/main/00_BACKEND/.agents/skills/api-designer
Command: npx skills add https://github.com/marketiv-id/marketiv-web --skill api-designer-marketiv-id

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Designing consistent, well-documented APIs is difficult: teams often ship endpoints with inconsistent naming, missing error contracts, no pagination strategy, and no versioning plan, which leads to breaking changes and painful client migrations. ## Core Features & Use Cases - OpenAPI 3.1 Specification Generation: Produces complete, lint-validated API contracts with reusable schemas, security schemes, and RFC 7807 error responses. - REST Design Guidance: Enforces resource-oriented URIs, correct HTTP method semantics, status codes, and consistent naming conventions. - Pagination, Versioning & Error Standards: Provides reference patterns for cursor/offset/keyset pagination, deprecation lifecycles, and structured error catalogs. - Use Case: When building a new backend service, ask for an API design and receive a resource model, endpoint specifications, and a validated OpenAPI YAML file ready for mock-server testing with Prism. ## Quick Start Design a versioned REST API for a user management service with cursor pagination and RFC 7807 error responses, delivered as an OpenAPI 3.1 specification.

Frequently Asked Questions about api-designer

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

FAQPage Schema
How do I design a REST API with OpenAPI 3.1?

Start by modeling resources and relationships, then define endpoints with proper HTTP methods and URIs. Write the OpenAPI 3.1 spec with reusable schemas and validate it using npx @redocly/cli lint before mocking with Prism.

What pagination strategy should I use for my API?

Use offset pagination for small datasets needing random page access, and cursor or keyset pagination for large or frequently changing datasets. Cursor pagination avoids expensive COUNT queries and prevents skipped or duplicate items.

How should REST APIs handle errors?

Return RFC 7807 Problem Details with Content-Type application/problem+json, including type, title, status, and detail fields. Use correct HTTP status codes and never expose stack traces or internal implementation details.

When should I version my API and how?

Version from day one using URI versioning like /v1/users, and bump the major version only for breaking changes such as removed fields or changed types. Support old versions for 6-12 months with Deprecation and Sunset headers before shutdown.

Can OpenAPI specs be used to generate client SDKs?

Yes, OpenAPI specs drive code generation for TypeScript, Python, and server stubs using tools like openapi-generator-cli. Including operationId values and examples improves the quality of generated clients.