skills.rest
doccker
docckerCOMMUNITY
Explore all skills by this author →
GitHub

api-design-safety

Validates REST API response design and downstream artifact completeness against common defect patterns.

1.0k|109|Updated Jan 4, 2026
Search Tags:#Validation#API Design#spring Boot#REST api#Excel export#Code review#Error handling
One-click install
npx skills add https://github.com/doccker/cc-use-exp --skill api-design-safety
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-safety
Source: https://github.com/doccker/cc-use-exp/tree/main/.cursor/skills/api-design-safety
Command: npx skills add https://github.com/doccker/cc-use-exp --skill api-design-safety

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

REST API responses often suffer from subtle design defects: Java generic overload ambiguity sends data into the wrong field, business errors get thrown as framework exceptions and surface as HTTP 500, and generated Excel/CSV/PDF artifacts silently succeed while missing fields that downstream consumers (WeChat import, reconciliation systems, third-party APIs) will reject. This Skill provides checklists and patterns to catch these defects before they reach production.

Core Features & Use Cases

  • Response Structure Safety: Prevents generic method overload ambiguity, clarifies message vs data field semantics, and standardizes null/empty handling across endpoints.
  • Status Code & Exception Discipline: Separates HTTP transport codes from business codes, and enforces using BusinessException instead of IllegalArgumentException so business errors return 200 + code 4xx instead of 500.
  • Downstream Artifact Validation: Enforces pre-generation completeness checks for Excel/CSV/PDF exports and batch pushes, listing missing business IDs and failing fast instead of silently emitting empty values.
  • Use Case: When building a WeChat mini-program shipping template export, the Skill guides you to validate mchId, transactionId, and shipping company fields upfront, throwing business errors with specific order numbers rather than generating a file WeChat will reject.

Quick Start

Ask the AI to review your REST API endpoint or export function against the api-design-safety rules before committing the code.

Frequently Asked Questions about api-design-safety

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

FAQPage Schema
How do I avoid Java generic overload ambiguity in API responses?▼

When returning a String, explicitly pass a message parameter like ApiResponse.success("uploaded", url), or use an explicit type witness such as ApiResponse.<String>success(data). Otherwise Java resolves the call to success(String message) and your data lands in the wrong field.

How should HTTP status codes differ from business status codes?▼

HTTP codes indicate transport-level outcomes (200, 401, 403, 500), while business results go in the response body code field. Business failures like missing resources should return HTTP 200 with a business code such as 404, reserving HTTP 500 for actual code exceptions.

Why does my exported Excel fail when imported by WeChat?▼

WeChat shipping templates require fields like mchId and transactionId; empty strings pass generation but are rejected on import. Validate all required fields before generating the file and throw a business error listing the specific order numbers that are missing values.

Should business errors throw IllegalArgumentException in Spring Boot?▼

No. Framework exceptions like IllegalArgumentException are handled as HTTP 500 with stack traces. Use a custom BusinessException so the global handler returns HTTP 200 with a business code and a user-friendly message, keeping 500 alerts reserved for real bugs.

What required fields must be checked before generating reconciliation files?▼

Cover three layers: business fields on each record (order number, amount), dependency configuration (mchId, API credentials, template IDs), and foreign key associations (payment records with transaction IDs, shipping packages with company and tracking number). Base the list on the downstream consumer's official documentation.

Related Skills

Explore More Software Engineering Skills→
nmoralescybernmoralescyber

reconciliation

Match balances across GL, bank statements, and subledgers into a consolidated workpaper.

Community
Advanced
WebWakaHubWebWakaHub
20

API Tester

Validate APIs for functional, security, and performance requirements.

Official
Advanced
cosmicstack-labscosmicstack-labs
364

api-testing

Validate REST and GraphQL APIs against OpenAPI schemas and contracts.

Official
Intermediate
program-the-brain-not-the-heartbeatprogram-the-brain-not-the-heartbeat

openapi-to-typescript

Convert OpenAPI 3.0 JSON or YAML specifications into TypeScript interfaces and type guards.

Community
Advanced