skills.rest
oriddd
oridddCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Defines REST API design rules for Spring Boot services including versioning, pagination, and error formats.

Updated Jun 25, 2026
Search Tags:#versioning#api design#openapi#rest api#pagination#spring boot#problem detail
One-click install
npx skills add https://github.com/oriddd/ai-toolkit --skill api-design-oriddd
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/oriddd/ai-toolkit/tree/main/copilot/public/skills/api-design
Command: npx skills add https://github.com/oriddd/ai-toolkit --skill api-design-oriddd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Designing consistent REST APIs across teams is hard: endpoints drift into verb-based URLs, status codes get misused, pagination shapes vary, and error responses lack a standard format. This Skill provides a single rulebook for Spring Boot services so every endpoint follows the same conventions before any controller code is written. ## Core Features & Use Cases - Resource and Verb Conventions: Enforces noun-based URLs with proper HTTP verb semantics, plus a full status code catalogue (200, 201, 202, 204, 4xx, 5xx) mapped to RFC 7807 ProblemDetail error bodies. - Versioning, Pagination, and Filtering: Covers URI vs media-type versioning with deprecation headers, offset vs cursor pagination, and simple or OData-style filtering grammars mapped to Spring Specifications. - Advanced Endpoint Patterns: Provides rules for multipart file-plus-JSON uploads, idempotency keys on unsafe verbs, async operations with Operation-Location polling, and OpenAPI-first vs code-first contract strategies. - Use Case: When adding a new endpoint to a Spring Boot service, apply this Skill to decide the URL shape, status codes, pagination approach, and error format, then pin the OpenAPI document as a CI snapshot test. ## Quick Start Apply the api-design skill to review the REST endpoint I am about to add and check it against the resource, status code, and pagination conventions.

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 API endpoints in Spring Boot?▼

Use noun-based URLs with HTTP verbs for actions, such as GET /api/v1/documents for listing and POST for creation. Return RFC 7807 ProblemDetail bodies for all 4xx and 5xx errors, and document every endpoint in an OpenAPI definition.

URI versioning vs media-type versioning for REST APIs?▼

URI versioning (/api/v1/...) is the default because it is easiest for consumers to reason about. Media-type versioning via the Accept header is cleaner for cache layers but harder for ad-hoc clients. Pick one scheme per organization.

How do I handle file upload with JSON metadata in Spring Boot?▼

Use multipart/form-data with two named @RequestPart parameters: one MultipartFile for the binary and one @Valid DTO for the JSON metadata. Configure max-file-size limits, stream large files instead of calling getBytes(), and map MaxUploadSizeExceededException to 413.

When should I use cursor pagination instead of offset pagination?▼

Use Spring Pageable offset pagination for datasets up to roughly 100,000 records with default size 20 and max 100. Switch to cursor pagination with an opaque pageToken when offset queries become too expensive on large datasets.

What status code should a REST API return for async operations?▼

Return 202 Accepted with an Operation-Location header pointing to an operation resource. Clients poll GET /api/v1/operations/{id} which returns a status of RUNNING, SUCCEEDED, or FAILED along with the result or error.

Should REST APIs use HATEOAS links in responses?▼

The default posture is flat JSON DTOs without _links. HATEOAS is only required when clients are autonomous agents that must discover navigation at runtime, which is rare in typical service integrations.

Related Skills

Explore More Software Engineering Skills→
hyxkleehyxklee

api-create

Generate API endpoints with Controller, UseCase, DTO, Service, and Repository layers from domain models.

Community
Intermediate
taipt1504taipt1504
3

api-design

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

Community
Advanced
MartiXDevMartiXDev

dotnet-api-quality

Improve ASP.NET Core APIs with validation, ProblemDetails, OpenAPI documentation, and consistent response contracts.

Official
Intermediate
infinith4infinith4
1

api-spec

Generate OpenAPI 3.0 specifications with schemas, paths, and examples for REST APIs.

Community
Advanced