internal-api-standards

Enforce DTO patterns and response organization for internal API endpoints.

1|Updated Jan 21, 2026

Search Tags:#design #documentation #api #backend #standards #dto

Ready to run

npx skills add https://github.com/pdylanross/barnacle --skill internal-api-standards

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: internal-api-standards
Source: https://github.com/pdylanross/barnacle/tree/main/.claude/skills/internal-api-standards
Command: npx skills add https://github.com/pdylanross/barnacle --skill internal-api-standards

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill addresses the inconsistency and potential for breaking changes in internal API endpoints by enforcing strict standards for Data Transfer Objects (DTOs), package organization, and documentation.

Core Features & Use Cases

DTO Enforcement: Ensures dedicated DTOs are used for API requests and responses, decoupling them from internal implementation types.
Structured DTO Organization: Provides a clear convention for organizing DTOs within pkg/api/ to mirror route structures.
Swagger Annotation Requirement: Mandates Swagger annotations for all internal API handlers to ensure discoverability and usability via tools like Swagger UI.
Use Case: When developing new internal API endpoints, this Skill guides developers to create clean, maintainable, and well-documented interfaces that are resilient to internal code refactoring.

Quick Start

Follow the DTO requirement to define dedicated DTOs for API request and response types.

Frequently Asked Questions about internal-api-standards

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

FAQPage Schema

Why use separate DTOs for internal API endpoints instead of internal domain types?▼

Using dedicated Data Transfer Objects for internal API endpoints decouples your API contracts from internal implementation types. This prevents breaking changes during backend code refactoring and ensures stable administrative interfaces under `/api/`.

What is the best way to organize API DTOs in a backend project?▼

The best way to organize API DTOs is to place them within a dedicated `pkg/api/` directory. Structuring these DTO packages to mirror your route hierarchy keeps internal API endpoints maintainable and easy to navigate.

How do I document internal API endpoints for Swagger UI?▼

You document internal API endpoints for Swagger UI by adding Swagger annotations directly to your API handlers. Mandating these annotations ensures endpoint discoverability and generates accurate API documentation automatically.

Do I need to map domain types to DTOs before returning API responses?▼

Yes, you must map internal domain types to DTOs before responding to API requests. This mapping step enforces strict API standards, ensuring internal implementation details never leak directly through administrative endpoints.

What are the limitations of relying on internal domain types for API responses?▼

Relying on internal domain types for API responses couples your endpoints to backend implementation details, increasing the risk of breaking changes. Without strict DTO enforcement, internal code refactoring can easily break API consumers.

Can I use these API standards for public-facing endpoints?▼

These API standards are specifically designed for internal management endpoints exposed under `/api/`. They focus on administrative backend services, DTO organization within `pkg/api/`, and internal API consistency.