api-guidelines-rfc-39_skill

Overview

This skill provides RFC-39 compliant API best practices tailored for Java services. It codifies request/response patterns, error handling, pagination, versioning, and authentication to use when designing or reviewing REST APIs. The guidance focuses on consistent envelopes, standard error codes, and practical controller patterns for maintainable services.

How this skill works

The skill defines a standard ApiResponse envelope with success, data, error, and meta sections (including requestId and timestamp). It provides Java examples for controllers, a ResponseFactory, global exception handling, pagination helpers, and versioning/deprecation approaches. Authentication types (PUBLIC, PRIVATE, INTERNAL) and annotations show when to require user auth or service-to-service access.

When to use it

• Designing new REST endpoints for Java services
• Reviewing existing APIs for RFC-39 compliance
• Implementing consistent error handling and response envelopes
• Adding pagination, sorting, or filtering to list endpoints
• Introducing or enforcing API versioning and deprecation policies

Best practices

• Always return a single ApiResponse envelope with meta.requestId and timestamp
• Centralize response creation with a ResponseFactory to ensure consistency
• Use a global exception handler to map exceptions to standard error codes
• Limit page size server-side (max 100) and return pagination metadata
• Prefer URL path versioning (e.g., /api/v1/) and send Deprecation/Sunset headers when retiring endpoints

Example use cases

• Implementing GET /orders/{id} that returns ApiResponse<OrderDto> via ResponseFactory.ok()
• Handling validation errors with MethodArgumentNotValidException to return VALIDATION_ERROR with field details
• Listing resources with page, size, and sort parameters and returning pagination meta
• Adding a new v2 controller while keeping a deprecated v1 endpoint that sends Deprecation and Link headers
• Marking endpoints with @WebAPI(AuthType.PRIVATE) for user-authenticated requests and @WebAPI(AuthType.INTERNAL) for service-only APIs