playbooks

home / skills / oimiragieo / agent-studio / apiresponse-class

apiresponse-class skill

/.claude/skills/_archive/dead/apiresponse-class

This skill helps ensure ApiResponse class structure adheres to coding standards, improving consistency, readability, and maintainability.

npx playbooks add skill oimiragieo/agent-studio --skill apiresponse-class

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.3 KB
---
name: apiresponse-class
description: Structure of ApiResponse class.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/src/main/java/com/example/ApiResponse.java'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Apiresponse Class Skill

<identity>
You are a coding standards expert specializing in apiresponse class.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

</instructions>

<examples>
Example usage:
```
User: "Review this code for apiresponse class compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill helps developers design, review, and refactor an ApiResponse class for JavaScript projects. It focuses on clear structure, consistent patterns, and predictable API shapes to improve maintainability and client interoperability. The guidance emphasizes small, testable methods and explicit status handling.

How this skill works

The skill inspects ApiResponse implementations for common concerns: status codes, payload shape, error wrapping, serialization, and immutability. It highlights anti-patterns (implicit side effects, mixed responsibilities) and suggests concrete refactors: separating metadata from data, normalizing error objects, and adding helpers for consistent response creation. It also recommends tests and examples for consumers.

When to use it

  • Creating a standardized response wrapper for HTTP APIs or internal services
  • Reviewing existing ApiResponse classes to reduce bugs and improve consistency
  • Refactoring code that mixes business logic and response formatting
  • Designing SDKs or client libraries that rely on uniform response shapes
  • Preparing code for strict typing or adding TypeScript compatibility

Best practices

  • Keep ApiResponse focused on representation: status, headers, metadata, and body only
  • Provide factory helpers (success, error, paginated) to reduce duplication
  • Avoid throwing inside serialization; return error objects with clear codes
  • Make instances immutable or use shallow freeze to prevent accidental mutation
  • Normalize error payloads with code, message, and optional details for clients

Example use cases

  • Wrap controller results so all endpoints return { status, data, meta } consistently
  • Replace ad-hoc error handling with ApiResponse.error({ code, message, details })
  • Introduce ApiResponse.paginated(data, pageInfo) to standardize pagination metadata
  • Refactor service layer to return ApiResponse objects instead of raw values
  • Add unit tests that assert ApiResponse factory outputs and JSON serialization

FAQ

Should ApiResponse include HTTP headers and status codes?

Yes—include status and a headers object if the class is used at the transport layer; otherwise keep it transport-agnostic and let the controller map to HTTP.

How do I handle validation errors consistently?

Return an error ApiResponse with a machine-friendly code, human message, and a details array that lists field errors; avoid embedding stack traces in production.