api-design

Define REST and HTTP API conventions for Figurio backend endpoints.

Updated Apr 6, 2026
One-click install
npx skills add https://github.com/cellarwood/figurio --skill api-design-cellarwood
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/cellarwood/figurio/tree/main/skills/api-design
Command: npx skills add https://github.com/cellarwood/figurio --skill api-design-cellarwood

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Help engineers design and change Figurio's backend HTTP APIs so they are predictable, safe, and maintainable, reducing payment, fulfillment, and integration regressions.

Core Features & Use Cases

  • Resource-oriented REST patterns for catalog, orders, generation-jobs, previews, and payments with plural collections and stable IDs.
  • Validation, idempotency, and error semantics including idempotency keys for charge-related writes, 409 for conflicts, and short actionable error payloads.
  • Stripe and webhook handling guidance with signature verification, event idempotency, and reconciliation best practices.
  • Testing and review expectations covering contract tests, idempotency, webhook replay handling, and edge cases for stateful workflows.

Quick Start

Draft an orders API that returns the canonical order resource after writes, validates ownership and state transitions, requires idempotency for payment-affecting endpoints, and verifies Stripe webhook signatures.

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 APIs with idempotency for payment endpoints?

To design REST APIs with idempotency for payment endpoints, enforce idempotency keys on charge-related writes, return canonical resources after writes, and use 409 status codes for conflicts to ensure predictable behavior.

What is the best way to handle Stripe webhook signature verification in a REST API?

Handling Stripe webhook signature verification in a REST API requires validating webhook signatures, enforcing event idempotency, and applying reconciliation best practices to prevent payment regressions and ensure safe fulfillment integration.

How do I structure error semantics in HTTP APIs for order lifecycle workflows?

Structuring error semantics in HTTP APIs for order lifecycle workflows involves returning short actionable error payloads, validating ownership, and using explicit state transitions to maintain predictable behavior across services.

Does this REST API design approach support custom generation job and preview delivery endpoints?

Yes, this REST API design approach supports custom generation job and preview delivery endpoints by applying resource-oriented REST patterns with plural collections and stable IDs across catalog, checkout, and operator-facing services.

What testing expectations should I follow when changing backend HTTP API conventions?

When changing backend HTTP API conventions, follow testing expectations covering contract tests, idempotency validation, webhook replay handling, and edge cases for stateful workflows to verify safe and maintainable integration.

Why do I need idempotency keys for charge-related writes in REST APIs?

You need idempotency keys for charge-related writes in REST APIs to prevent duplicate charges during network retries, ensure safe payment processing, and maintain consistent state transitions across order lifecycle workflows.