skills.rest
coco-research
coco-researchCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Design REST and GraphQL APIs with resource-oriented naming and HTTP semantics.

264|11|Updated Apr 25, 2026
Search Tags:#versioning#error handling#api design#rest#graphql#pagination#dataloaders
One-click install
npx skills add https://github.com/coco-research/coco --skill api-design-principles-coco-research
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/coco-research/coco/tree/main/skills/api-design-principles
Command: npx skills add https://github.com/coco-research/coco --skill api-design-principles-coco-research

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and assets (resource) components.

What problem does it solve?

This Skill helps teams design APIs that are easy to understand, easy to use, and resilient as products grow, reducing friction for both internal and external developers.

Core Features & Use Cases

  • REST API Design: Define resource-oriented endpoints, choose correct HTTP methods, and map actions to clear status codes.
  • GraphQL API Design: Shape strong schemas, build mutation payloads, and avoid performance issues like N+1 query patterns.
  • Operational Standards: Establish pagination, filtering, versioning, error handling, documentation, and review checklists for production-ready APIs.
  • Use Case: A platform team can use this Skill to review a new user service before launch and ensure its routes, schema, and error responses follow consistent standards.

Quick Start

Ask for a review of your API design and provide the current endpoints or GraphQL schema so the Skill can suggest improvements to structure, usability, and reliability.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema
How do I design REST API endpoints that are resource-oriented and follow correct HTTP semantics?▼

To design REST API endpoints, define resource-oriented naming structures, map actions to correct HTTP methods, and apply clear status codes. This ensures your API routes are intuitive, scalable, and maintainable for developers.

What is the best way to prevent N+1 query issues in GraphQL schemas?▼

Prevent N+1 query issues in GraphQL by implementing DataLoaders for batched data fetching. This approach structures your schema-first design to avoid performance bottlenecks when resolving complex nested resource hierarchies.

How should I structure API pagination, versioning, and error handling for production?▼

Structure API pagination, versioning, and error handling by establishing operational standards for filtering and structured error responses. Setting these team design standards ensures your API is reliable and production-ready.

Can I use this approach to review and refactor an existing API specification?▼

Yes, you can review and refactor existing API specifications by evaluating current endpoints or GraphQL schemas against resource-oriented naming, HTTP semantics, and structured error handling standards to suggest usability improvements.

REST vs GraphQL: how do I choose the right approach for my API design?▼

Choosing between REST and GraphQL depends on your data needs: REST uses resource-oriented endpoints with HTTP methods, while GraphQL uses schema-first patterns with mutations and DataLoaders to prevent N+1 queries for complex hierarchies.

Related Skills

Explore More Software Engineering Skills→
coreindustriescoreindustries
1

api

Design, scaffold, and document RESTful and GraphQL APIs with OpenAPI schemas.

Community
Intermediate
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
Typeless-GitTypeless-Git
1

backend-testing

Create unit, integration, and API tests for backend logic with Jest, Pytest, or Mocha/Chai.

Official
Intermediate
hpsgdhpsgd

api-design

Design RESTful API contracts with resource models, HTTP methods, and error handling.

Official
Advanced