skills.rest
mahg-es
mahg-esOFFICIAL
Explore all skills by this author →
WebsiteGitHub

api-design

Design REST and GraphQL APIs with OpenAPI 3.1 specifications.

3|Updated May 28, 2026
Search Tags:#design#authentication#api#openapi#specification#rest#graphql
One-click install
npx skills add https://github.com/mahg-es/araya --skill api-design-mahg-es
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/mahg-es/araya/tree/main/skills/api-design
Command: npx skills add https://github.com/mahg-es/araya --skill api-design-mahg-es

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

API design often suffers from ad-hoc specifications leading to inconsistent endpoints, missing schemas, and integration delays. This skill ensures a complete, standardized OpenAPI 3.1 contract before implementation.

Core Features & Use Cases

  • OpenAPI 3.1 compliant API contract with clear paths, schemas, security, and versioning.
  • Inter-team alignment by defining resources, operations, and error handling upfront.
  • Use Case: Design a new user management API with JWT authentication and versioned endpoints to support frontend and mobile apps.

Quick Start

Provide a complete OpenAPI 3.1 specification for a REST/GraphQL API including endpoints, schemas, and authentication.

Frequently Asked Questions about api-design

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 specifications?▼

Designing REST APIs with OpenAPI 3.1 involves gathering requirements, defining resource models, standardizing errors, adding authentication, and versioning endpoints to produce a complete specification contract for development teams.

How do I standardize error handling and authentication across API endpoints?▼

Standardize API errors and authentication by applying an OpenAPI 3.1 specification that defines security schemas and consistent error responses across all resources, ensuring inter-team alignment before implementation.

Can I use OpenAPI 3.1 to design a GraphQL API specification?▼

Yes, you can design GraphQL APIs using OpenAPI 3.1 standards by defining schemas, queries, mutations, and authentication to produce a complete specification contract for your GraphQL endpoints.

What is the best way to align frontend and mobile teams on API versioning?▼

The best way to align teams on API versioning is defining versioned endpoints and resources upfront in a complete OpenAPI 3.1 specification, ensuring consistent integration across frontend and mobile applications.

Why do I need a complete API specification before starting implementation?▼

You need a complete API specification before implementation to prevent ad-hoc designs that cause inconsistent endpoints, missing schemas, and integration delays across development teams. A standardized OpenAPI 3.1 contract ensures upfront alignment.

How do I validate an OpenAPI document for my user management API?▼

Validate an OpenAPI document for a user management API by ensuring the complete specification includes correctly defined endpoints, JWT authentication schemas, request/response models, error handling, and versioning against OpenAPI 3.1 standards.

Related Skills

Explore More Software Engineering Skills→
icartshicartsh
4

api-designer

Design RESTful and GraphQL APIs with OpenAPI 3.0 specifications.

Community
Advanced
ccfccf

openapi-spec-generation

Generate and validate OpenAPI 3.1 specifications from design or code sources.

Community
Advanced
Axel-DaMageAxel-DaMage
2

api-designer

Design REST and GraphQL APIs with OpenAPI 3.1 specifications.

Community
Advanced
erichowenserichowens
181

api-architect

Design and validate REST, GraphQL, and gRPC API contracts and architectures.

Community
Advanced