skills.rest
AI-Foundry-Core
AI-Foundry-CoreOFFICIAL
Explore all skills by this author →
GitHub

api-design-principles

Design RESTful and GraphQL API patterns with schema, versioning, and error handling guidance.

4|Updated Mar 3, 2026
Search Tags:#design#versioning#api#rest#graphql#best-practices#error-handling
One-click install
npx skills add https://github.com/AI-Foundry-Core/ril-agents --skill api-design-principles-ai-foundry-core
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/AI-Foundry-Core/ril-agents/tree/main/plugins/backend-development/skills/api-design-principles
Command: npx skills add https://github.com/AI-Foundry-Core/ril-agents --skill api-design-principles-ai-foundry-core

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

Crafting consistent, scalable REST and GraphQL APIs is challenging; this skill provides a structured approach to design, document, and evolve APIs with best practices.

Core Features & Use Cases

  • REST Principles: Resource-oriented design, proper HTTP methods, and meaningful URLs.
  • GraphQL Patterns: Typed schemas, efficient resolvers, and effective pagination.
  • Guidance & Standards: Versioning, error handling, monitoring, and deprecation strategies to avoid breaking clients.
  • Real-world scenario: blueprint and review process for a new service's API surface and schema.
  • Use case: enforce a team's API design standard across multiple services.

Quick Start

Draft a complete API blueprint for a new service, including a REST resource map and a GraphQL schema.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema
What are the best practices for REST API resource-oriented design and URL structure?▼

REST API design best practices involve structuring meaningful URLs and applying proper HTTP methods for resource-oriented interfaces. This skill codifies schema design into actionable guidance to ensure consistent, scalable services.

How do I design a GraphQL schema with typed fields and efficient pagination?▼

Designing a GraphQL schema with typed fields and efficient pagination involves structuring typed schemas and optimizing resolvers. This skill codifies GraphQL patterns into actionable guidance for scalable service interfaces.

How do I handle API versioning and deprecation to avoid breaking clients?▼

API versioning and deprecation strategies prevent breaking changes by codifying standards for evolving schemas. This skill provides actionable guidance on versioning, error handling, and deprecation to maintain client compatibility.

Can I use this to enforce API design standards across multiple services?▼

Yes, you can enforce API design standards across multiple services using this skill's blueprint and review process. It codifies REST and GraphQL standards into actionable guidance for teams reviewing specifications and enforcing consistency.

What's the best way to draft a complete API blueprint for a new service?▼

The best way to draft a complete API blueprint is to map REST resources and define GraphQL schemas systematically. This skill structures the design process from schema creation to endpoint evolution into actionable guidance.

Related Skills

Explore More Software Engineering Skills→
musujmusuj

phase-1-schema

Define project terminology, entities, relationships, and data structures.

Community
Intermediate
hffmnnjhffmnnj
39

api-docs

Generate API reference documentation from OpenAPI specs and GraphQL schemas.

Community
Advanced
cenjiecenjie

api-security-hardening

Secure REST APIs with authentication, rate limiting, CORS, and input validation.

Community
Advanced
ref-docsref-docs

constitution-enforcer

Enforce the 9 Constitutional Articles and Phase -1 Gates before implementation.

Official
Advanced