api-design-principles

Design REST and GraphQL APIs with schema-first contracts and validation rules.

Updated Jul 15, 2023

Search Tags:#design #versioning #GraphQL #REST #patterns #APIs

Ready to run

npx skills add https://github.com/algusaem/algusaem-portfolio --skill api-design-principles-algusaem

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/algusaem/algusaem-portfolio/tree/main/.claude/skills/api-design-principles
Command: npx skills add https://github.com/algusaem/algusaem-portfolio --skill api-design-principles-algusaem

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill provides a structured approach to designing and evaluating REST and GraphQL APIs, reducing ambiguity and aligning teams on consistent patterns.

Core Features & Use Cases

Schema-first design guidance for both REST resources and GraphQL types.
Practical versioning, pagination, error handling, and documentation patterns.
Use Case: When starting a new API service, generate a coherent API contract, including endpoints, schemas, and error schemas.

Quick Start

Provide a high-quality API design outline for a new service using REST and GraphQL patterns. For example, define a User API with endpoints for create, read, update, delete, and a User type with fields and relationships.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema

What are the key principles for designing REST and GraphQL APIs?▼

Key REST and GraphQL API design principles include schema-first design, consistent versioning strategies, standardized error handling, proper pagination, and thorough documentation practices to enforce structured API contracts.

How do I create an API contract for a new service?▼

To create an API contract for a new service, apply schema-first design guidelines to define REST resources or GraphQL types, including specific endpoints, data schemas, and error schemas for operations like create, read, update, and delete.

What is the best way to handle API versioning and pagination?▼

The best way to handle API versioning and pagination involves applying structured design patterns that enforce consistent validation rules across teams, reducing ambiguity and aligning on coherent API contract management strategies.

When should I use schema-first design for APIs?▼

You should use schema-first design for APIs when starting a new service to ensure a coherent contract, defining GraphQL types and REST resources upfront before implementation to align teams on consistent patterns.

Does this approach support both REST resources and GraphQL types?▼

Yes, this approach supports both REST resources and GraphQL types, providing structured design guidance, validation rules, and principled patterns for defining endpoints, schemas, and relationships across both architectural styles.