skills.rest
yairbederman
yairbedermanCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Design REST and GraphQL APIs with versioned interfaces and observability headers.

Updated Dec 24, 2025
Search Tags:#design#architecture#versioning#api#rest#graphql#observability
One-click install
npx skills add https://github.com/yairbederman/EngineeringAgency --skill api-design-yairbederman
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/yairbederman/EngineeringAgency/tree/main/skills/api-design
Command: npx skills add https://github.com/yairbederman/EngineeringAgency --skill api-design-yairbederman

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Design REST and GraphQL APIs with robust versioning, observability, and architectural best practices to reduce integration risk and churn.

Core Features & Use Cases

  • API design guidelines for REST and GraphQL, including versioning strategies, error handling, and observability headers.
  • Review and refine API specifications to ensure consistency, scalability, and maintainability across services.
  • Use cases include designing new APIs, migrating versions, and auditing existing endpoints for improvements.

Quick Start

Apply these guidelines to your API spec to structure endpoints, versioning, and observability.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design REST and GraphQL APIs with scalable architecture and versioning?▼

To design REST and GraphQL APIs with scalable architecture, apply structured guidelines for URL endpoints, HTTP methods, response codes, and clear versioning strategies to reduce integration risk and churn.

What is the best way to plan an API version migration without breaking existing clients?▼

The best way to plan an API version migration is using versioned interface guidelines that structure endpoints and maintain consistency, ensuring smooth transitions while auditing existing services for improvements.

How do I add observability headers to my API specification for better service monitoring?▼

Add observability headers to your API specification by applying built-in guidelines that ensure observability requirements are met across services, enabling better tracking and monitoring of API requests.

Does this API design approach work for both designing new APIs and reviewing existing specifications?▼

Yes, this API design approach works for both designing new APIs and reviewing existing specifications, providing guidelines for URL structure, HTTP methods, response codes, versioning, and a security checklist.

What security checklist should I follow when building robust APIs with clear versioning?▼

When building robust APIs with clear versioning, follow the included security checklist alongside guidelines for URL structure, HTTP methods, response codes, and observability headers to ensure comprehensive protection.

When should I not use REST versus GraphQL for my API architecture?▼

REST and GraphQL serve different API architecture needs; this approach provides design guidelines for both, helping you review specifications and choose the appropriate structure based on your scalability and data-fetching requirements.

Related Skills

Explore More Software Engineering Skills→
Fr-e-dFr-e-d
157

architecture-extract

Analyze project directory structures to generate architectural summaries.

Community
Basic
dodygdodyg

dotnet-api-docs

Generate DocFX metadata, OpenAPI specs, and versioned HTML documentation for .NET projects.

Community
Advanced
missBergmissBerg
3

eg-multi-tenant

Provision per-tenant Envoy Gateway isolation and policies in Kubernetes.

Community
Advanced
GaryOcean428GaryOcean428

api-design-validation

Validate REST API endpoint naming, HTTP methods, and status codes.

Community
Intermediate