api-design

Design and review AEP-compliant REST/gRPC APIs with resource modeling and standard methods.

2|1|Updated Mar 8, 2026
One-click install
npx skills add https://github.com/mattstruble/skills --skill api-design-mattstruble
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/mattstruble/skills/tree/main/api-design
Command: npx skills add https://github.com/mattstruble/skills --skill api-design-mattstruble

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Design and review REST/gRPC APIs following AEP guidelines, focusing on resource modeling, standard methods, and consistent naming, so teams can auto-generate clients and enforce contracts.

Core Features & Use Cases

  • Resource-oriented design with clear resource hierarchies
  • Standard methods mapping (Get, List, Create, Update, Delete, Custom)
  • Guidance for pagination, error handling, and naming consistency
  • Use Case: review an existing API for consistency or design a new API from scratch

Quick Start

Provide a high-level API spec sketch for a new resource hierarchy and generate an example OpenAPI snippet.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design a resource-oriented REST API with standard methods?

Structure REST API pagination and error handling by using proper pagination techniques and RFC 9457 error formats. Following AEP guidelines ensures consistent pagination and standardized error responses across your resource models.

What is the best way to model resource hierarchies for OpenAPI specs?

Review existing APIs for consistency by checking resource-oriented paths, standard methods mapping, and naming conventions. Enforcing AEP guidelines ensures proper pagination, error handling, and merge-patch updates across your resource models.

How does merge-patch update work with AEP compliant APIs?

Handle API state transitions by using custom methods alongside standard methods like Get and Update. AEP guidelines enforce consistent naming and custom method structures for state changes within resource-oriented API designs.

Do I need protobuf definitions to use AEP resource modeling?

Underscore_time fields enforce naming consistency for time-related data in AEP-compliant APIs. This convention standardizes field naming across resource models, ensuring clear contracts for auto-generating clients.