skills.rest
schalappe
schalappeCOMMUNITY
Explore all skills by this author →
Website𝕏@HakimKoneGitHub

api-design-principles

Guide REST and GraphQL API design with resource modeling and pagination.

Updated Aug 23, 2026
Search Tags:#authentication#error handling#api design#rest#graphql#webhooks#pagination
One-click install
npx skills add https://github.com/schalappe/skills --skill api-design-principles-schalappe
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/schalappe/skills/tree/main/api-design-principles
Command: npx skills add https://github.com/schalappe/skills --skill api-design-principles-schalappe

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

It helps you avoid inconsistent, insecure, and hard-to-evolve API designs by providing a clear set of REST and GraphQL principles and practical patterns.

Core Features & Use Cases

  • REST + GraphQL decisioning: choose resource-oriented REST for CRUD and schema-driven GraphQL for complex graphs and client-driven data needs.
  • Endpoint-shaping patterns: structure collections, nesting depth, pagination (offset vs cursor), and sparse fieldsets.
  • Production-ready behavior: enforce consistent error formats, correct HTTP status codes, secure authentication/authorization, and robust versioning/deprecation.
  • Event and long-running workflows: design webhooks and async flows using 202 Accepted, signed webhook delivery, retries, and idempotent receivers.
  • Use case examples: when adding pagination and filtering to a new users endpoint, evolving an API without breaking clients, or specifying webhook delivery semantics for third-party integrations.

Quick Start

Use the api-design-principles skill to review or draft an API specification (REST and/or GraphQL) covering routing, schemas, pagination, error handling, auth, versioning, and webhook/async behavior for the described system.

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 and GraphQL APIs with proper pagination and error handling?▼

Design REST and GraphQL APIs by applying resource modeling, offset versus cursor pagination, sparse fieldsets, and structured error formats with correct HTTP status codes to ensure consistent, production-ready interfaces.

When should I choose REST versus GraphQL for my API design?▼

Choose resource-oriented REST for standard CRUD operations and schema-driven GraphQL for complex data graphs and client-driven queries, applying consistent HTTP semantics and secure object-level authorization across both.

What is the best way to design secure webhooks and asynchronous API workflows?▼

Design secure webhooks and asynchronous API workflows by returning 202 Accepted for long-running tasks, implementing signed webhook delivery, enforcing idempotent receivers, and defining clear async status flows with retries.

How do I evolve an API without breaking existing clients?▼

Evolve an API without breaking clients by planning robust versioning and deprecation strategies, maintaining structured error contracts, and applying consistent HTTP semantics throughout the endpoint schema updates.

How do I structure API authentication and object-level authorization correctly?▼

Structure API authentication and authorization by enforcing secure object-level authorization checks, maintaining consistent HTTP semantics, and defining structured error contracts for unauthorized access attempts.

Related Skills

Explore More Software Engineering Skills→
itentialitential
13

itential-lcm

Automates lifecycle management of resources, instances, and actions in Itential Lifecycle Manager.

Official
Advanced
camilooscargbaptistacamilooscargbaptista
7

api-documentation

Generate and review OpenAPI 3.1 specs for REST and GraphQL APIs.

Community
Intermediate
Pratikkadam254Pratikkadam254

convex-http-actions

Define and manage HTTP endpoints and webhook processing for Convex applications.

Community
Advanced
mpsuessermpsuesser
22

effect-http-api

Build schema-first typed HTTP APIs with Effect's HttpApi module.

Community
Advanced