api-design

Design REST API standards and endpoint contracts for Spring Boot services.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Inconsistent or non-production-ready REST APIs cause bugs, unclear error handling, poor performance at scale, and missing documentation; this skill provides concrete conventions and patterns to standardize API design for Spring Boot services.

Core Features & Use Cases

  • HTTP methods & status codes: guidance on correct method selection, idempotency, and standard success and error codes.
  • URL conventions & versioning: resource-based paths, kebab-case, and per-resource versioning rules to avoid breaking clients.
  • Error format (RFC 7807): ProblemDetail-based error responses and a global RestControllerAdvice strategy.
  • Pagination patterns: offset, cursor, and keyset approaches with implementation notes and trade-offs.
  • Validation, rate limiting, and idempotency: bean validation recommendations, rate-limit headers, and idempotency key patterns for safe retries.
  • OpenAPI documentation: examples for OpenAPI configuration, annotations, and Swagger UI setup.
  • Operations: file upload/download, bulk operations, async jobs with polling and SSE for long-running tasks.

Quick Start

Ask the skill to design REST endpoints for an Orders service including RFC 7807 error responses, cursor pagination, idempotency, and OpenAPI annotations.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I implement RFC 7807 ProblemDetail error responses in a Spring Boot REST API?

RFC 7807 ProblemDetail error responses in a Spring Boot REST API are implemented using a global RestControllerAdvice strategy to standardize error formats across all endpoints. This ensures consistent error handling and clear client communication.

What is the best way to handle pagination in Spring Boot REST APIs?

Pagination in Spring Boot REST APIs can be handled using offset, cursor, or keyset patterns. Each approach has specific implementation notes and trade-offs regarding performance and scalability at production scale.

How do I add OpenAPI annotations and Swagger UI to a Spring Boot WebFlux project?

OpenAPI annotations and Swagger UI are added to a Spring Boot WebFlux project by applying specific OpenAPI configuration examples and annotation patterns to document endpoint contracts and expose interactive API documentation.

Does this API design skill apply to both Spring Boot MVC and WebFlux projects?

Yes, this API design skill applies to both Spring Boot MVC and WebFlux projects using Java 17+. It provides concrete conventions for defining endpoints, validation, idempotency handling, and rate limiting headers across both reactive and blocking architectures.

How do I implement idempotency handling and safe retries for REST endpoints?

Idempotency handling and safe retries for REST endpoints are implemented using specific idempotency key patterns. This ensures that duplicate requests from network retries do not cause duplicate state changes or side effects.