api-design

Design REST and GraphQL interfaces with resource-based URLs and explicit schemas.

482|100|Updated Apr 9, 2026
One-click install
npx skills add https://github.com/agulli/atlas-agents --skill api-design-agulli
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/agulli/atlas-agents/tree/main/ch09_agent_skills/skills/api-design
Command: npx skills add https://github.com/agulli/atlas-agents --skill api-design-agulli

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps engineers design and review clean, well-structured API interfaces (REST and GraphQL), ensuring predictable endpoints and strong schemas.

Core Features & Use Cases

  • Identify domain objects and group by relationship.
  • Design resource hierarchies with plural nouns and no verbs in URLs.
  • Define schemas with field types, required/optional, examples, and validations.
  • Define a consistent error envelope and proper HTTP status usage.
  • Support cursor-based pagination and versioning in URLs.

Quick Start

Describe your API domain and I will generate a complete REST/GraphQL design outline.

Frequently Asked Questions about api-design

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

FAQPage Schema
What makes a clean REST API design predictable and easy to use?

Cursor-based pagination improves API stability by using opaque cursors to fetch subsequent result pages, preventing data shifting or duplication issues common with offset-based pagination during real-time data modifications.

How do I define a consistent error envelope and HTTP status codes for my API?

To define a consistent API error envelope, standardize your JSON error response structure with clear codes and messages, and apply proper HTTP status usage to indicate request outcomes uniformly across all endpoints.

What is the best way to version REST API endpoints in URLs?

The best way to version REST API endpoints is by including the version number directly in the URL path, which provides explicit routing and ensures predictable interface evolution without breaking existing client integrations.

How do I design GraphQL schemas with required and optional field validations?

Design GraphQL schemas by explicitly defining field types, marking fields as required or optional, and adding validation rules directly in the schema definitions to enforce strict data contracts for API consumers.

Can I use this API design approach for both REST and GraphQL interfaces?

Yes, this API design approach works for both REST and GraphQL interfaces, applying consistent principles like explicit schemas, domain object identification, and clear error handling to ensure predictable endpoints across either protocol.