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

cc-api-design-safety

Validates REST API response design and downstream file export completeness.

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 cc-api-design-safety
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cc-api-design-safety
Source: https://github.com/doccker/cc-use-exp/tree/main/.codex/skills/cc-api-design-safety
Command: npx skills add https://github.com/doccker/cc-use-exp --skill cc-api-design-safety

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

REST API responses often suffer from field misplacement, ambiguous types, inconsistent null handling, and misused HTTP status codes, while generated downstream artifacts (Excel/CSV/PDF exports, reconciliation files, third-party pushes) can appear successful yet silently fail when required fields are missing. This Skill provides defensive design rules and checklists to prevent these defects before they reach consumers.

Core Features & Use Cases

  • API Response Design Rules: Prevents Java generic overload ambiguity, clarifies message vs data field semantics, standardizes null/empty handling, and separates HTTP status codes from business codes.
  • Downstream Artifact Integrity Validation: Enforces pre-generation completeness checks for required fields (business fields, dependency configs, foreign-key associations) with explicit business errors listing affected IDs instead of silent empty-value fallbacks.
  • Exception Type Discipline: Distinguishes BusinessException (HTTP 200 + business code) from framework exceptions (HTTP 500) so business errors are not misreported as system failures.
  • Use Case: When building a WeChat mini-program shipping template export, the Skill ensures mchId, transactionId, and shipping company fields are validated upfront, failing the whole export with specific order numbers rather than producing a file the downstream platform rejects.

Quick Start

Ask the AI to review your REST API response structure or export logic using the cc-api-design-safety rules before committing the code.

Frequently Asked Questions about cc-api-design-safety

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

FAQPage Schema
How do I design a safe REST API response structure in Spring Boot?▼

Use a unified ApiResponse with code, message, and data fields where message holds user-readable text and data holds business payloads. Return HTTP 200 with a business code for expected failures, and reserve HTTP 500 for actual code exceptions.

How to validate required fields before generating Excel export files?▼

Collect all required fields across three layers: business fields, dependency configs, and foreign-key associations. Validate before building the workbook, and throw a business error listing the specific order IDs missing each field instead of writing empty strings.

Why does my Java ApiResponse put data into the message field?▼

Java overload resolution matches String arguments to success(String message) instead of success(T data). Fix it by explicitly passing a message parameter, using an explicit generic type witness, or wrapping the value in a DTO.

Should business errors return HTTP 500 or HTTP 200?▼

Expected business failures should return HTTP 200 with a business code in the response body via a custom BusinessException. HTTP 500 should be reserved for genuine code bugs and system failures so monitoring alerts stay meaningful.

Does this guidance apply to Go and TypeScript backends?▼

Yes, the same principles apply across Java Spring Boot, Go Gin with excelize, TypeScript with ExcelJS, and Python FastAPI. The reference file includes complete multi-language implementations of the pre-export validation pattern.

Related Skills

Explore More Software Engineering Skills→
WhaleylawWhaleylaw

contract-testing-specialist

Validate API request and response contracts using Zod, Pact, and OpenAPI validators.

Community
Advanced
OM-bit-hubOM-bit-hub

contract-test

Automate contract testing between services with Pact and OpenAPI.

Community
Advanced
pacphipacphi
6

contract-testing

Automate consumer-driven contract testing for microservices and API contracts.

Community
Advanced
SaturateSaturate

api-design

Generate OpenAPI specs and TypeScript types from contract-first API designs.

Community
Advanced