skills.rest
korallis
korallisCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Design REST and GraphQL API contracts with endpoint structures and versioning.

90|10|Updated Nov 8, 2025
Search Tags:#api design#microservices#rest#graphql#api documentation#service contract
One-click install
npx skills add https://github.com/korallis/Droidz --skill api-design-korallis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/korallis/Droidz/tree/main/droidz_installer/payloads/droid_cli/default/skills/api-design
Command: npx skills add https://github.com/korallis/Droidz --skill api-design-korallis

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill addresses the complexity of designing REST and GraphQL APIs, ensuring they are scalable, maintainable, and adhere to industry best practices.

Core Features & Use Cases

  • RESTful Endpoint Design: Guides the creation of resource-based URLs, proper HTTP method usage, and consistent response structures.
  • GraphQL Schema Definition: Facilitates the design of typed schemas, efficient resolvers, and robust error handling.
  • Documentation Standards: Promotes the use of OpenAPI/Swagger for REST and schema descriptions for GraphQL.
  • Use Case: When starting a new microservice, use this skill to define its public API contract, ensuring clear communication and future compatibility.

Quick Start

Use the api-design skill to design a REST API for managing user profiles.

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 for microservices that stays maintainable?▼

To design a maintainable REST API for microservices, define resource-based URLs, use HTTP methods correctly, and standardize response structures. This approach ensures clear service contracts and future compatibility across distributed architectures.

What is the best way to structure GraphQL schemas and handle errors?▼

The best way to structure GraphQL schemas is to define strict, typed schemas with efficient resolvers. Robust error handling within these schemas ensures reliable query execution and maintainable service contracts for clients.

How do I write API documentation for REST and GraphQL endpoints?▼

Write API documentation by leveraging OpenAPI or Swagger for REST endpoints and detailed schema descriptions for GraphQL. This standardizes your service contracts, ensuring clear communication and integration for public-facing services.

What should I include in a request and response contract for API versioning?▼

A request and response contract for API versioning should include explicit endpoint structures, data models, and authentication methods. Systematic versioning within the contract ensures backward compatibility as your microservice evolves.

When should I prioritize GraphQL over RESTful endpoint design?▼

Prioritize GraphQL over RESTful endpoint design when clients require highly flexible data fetching and typed schemas. REST remains effective for standardized resource-based URLs and consistent caching in public-facing services.

Related Skills

Explore More Software Engineering Skills→
gvkhoslagvkhosla
49

architecture-strategist

Analyze code changes for architectural compliance with SOLID principles and microservice boundaries.

Community
Advanced
ChenYCLChenYCL

api-docs

Generate API documentation and OpenAPI 3.0 specs from code or descriptions.

Community
Intermediate
microwindmicrowind
65

API网关设计

Design API gateways for routing, security, and traffic management in microservices.

Official
Advanced
erichowenserichowens
181

api-architect

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

Community
Advanced