api-design-principles

name	api-design-principles
description	Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

API Design Principles

Purpose

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

This skill provides operational guidance for API Design Principles, including tool usage patterns, workflows, and quality expectations aligned with Syncolab skill standards.

When to Use

• Use when the user needs help with API Design Principles.
• When integrations for this domain are available and the task matches the workflows below.

When NOT to Use

• When the task is unrelated to API Design Principles or covered by a more specific skill.
• When required integrations or credentials are unavailable.

Expected Outcome

• Correct use of domain tools with verified results (not fabricated).
• Clear summary of actions taken, data returned, and recommended next steps.
• Errors and missing permissions reported explicitly.

Inputs to Gather

• User goal, constraints, and any identifiers (URLs, IDs, project keys).
• Available tool sets and connection status.
• Relevant context from related systems before destructive writes.

Workflow

1. Confirm the request maps to API Design Principles and required tools are available.
2. Gather identifiers and scope (project, channel, repo, date range, etc.).
3. Follow the domain guidance below; prefer list/search before get/update when applicable.
4. Execute tool calls using schemas from the integration; never invent tool output.
5. Summarize results and offer logical follow-ups.

API Design Principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

Use this skill when

• Designing new REST or GraphQL APIs
• Refactoring existing APIs for better usability
• Establishing API design standards for your team
• Reviewing API specifications before implementation
• Migrating between API paradigms (REST to GraphQL, etc.)
• Creating developer-friendly API documentation
• Optimizing APIs for specific use cases (mobile, third-party integrations)

Do not use this skill when

• You only need implementation guidance for a specific framework
• You are doing infrastructure-only work without API contracts
• You cannot change or version public interfaces

Instructions

1. Define consumers, use cases, and constraints.
2. Choose API style and model resources or types.
3. Specify errors, versioning, pagination, and auth strategy.
4. Validate with examples and review for consistency.

Refer to resources/implementation-playbook.md for detailed patterns, checklists, and templates.

Resources

• resources/implementation-playbook.md for detailed patterns, checklists, and templates.

Tool Availability Rules

Access	Behavior
Full tool access	Execute workflows, verify outputs, report errors.
Read-only	Inspect and plan; provide exact commands or dispatch request for writes.
No integration	State limitation; do not fabricate API results.

Related tool sets

• postman
• openai

Review / Decision / Execution Criteria

• Prefer smallest safe change; confirm destructive actions with the user.
• Use evidence from tool responses; cite IDs and links when present.
• Match integration-specific conventions (JQL, RFC3339, A1 notation, etc.).

Output Format

Report:

1. What was requested and what was done.
2. Key results (tables or bullets).
3. Errors, blockers, or missing permissions.
4. Suggested next steps.

Quality Bar

• Specific, actionable, and grounded in tool output.
• Concise unless the user asked for detail.
• Respect rate limits, pagination, and API semantics.

Safety and Boundaries

• Do not commit secrets, tokens, or PII into skills or user-visible logs.
• Do not fabricate validation, send, or write confirmations.
• Confirm destructive operations (delete, destroy, mass update) when appropriate.

Escalation / Dispatch Rules

• If the task spans multiple domains, use or suggest related skills via relationships.skills.
• If write access is required but unavailable, dispatch or ask the user to enable tools.

References

• Legacy content migrated from skills/old_skills.json (api-design-principles).
• skills/skill.instruction.md, skills/meta.instructions.md