# Api And Interface Design

> Guide stable API and interface design. Use when creating or changing public module boundaries, REST or GraphQL endpoints, event contracts, SDK methods, data transfer objects, error envelopes, or cross-team interfaces.

- **Type:** Skill
- **Install:** `agentstack add skill-hsienw-ai-agent-engineering-playbook-api-and-interface-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HsienW](https://agentstack.voostack.com/s/hsienw)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HsienW](https://github.com/HsienW)
- **Source:** https://github.com/HsienW/ai-agent-engineering-playbook/tree/master/skills-contract-boundaries/api-and-interface-design

## Install

```sh
agentstack add skill-hsienw-ai-agent-engineering-playbook-api-and-interface-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# API and Interface Design

## Skill Interface

- Name: api-and-interface-design.
- Description: Guide stable API and interface design for public module boundaries, REST or GraphQL endpoints, event contracts, SDK methods, data transfer objects, error envelopes, and cross-team interfaces.
- Parameters: Target interface or contract, expected consumers, request and response shapes, error model, compatibility requirements, versioning expectations, and available schema or test commands.
- Instructions: Use this skill before implementing or changing a public contract. Define the contract first, check backward compatibility, make runtime validation explicit, and verify behavior with contract or schema tests.

Design contracts before implementation. Treat every public shape as something
another caller may depend on, even if the current codebase has only one caller.

## Process

1. Identify consumers, owners, and compatibility expectations.
2. Define the request, response, event, error, and versioning contract.
3. Separate domain types from transport types.
4. Validate untrusted input at runtime.
5. Add unknown-field and future-version behavior.
6. Write examples for success, validation failure, upstream failure, timeout,
   cancellation, and permission denial.
7. Verify the implementation against the contract, not against incidental
   current behavior.

## Design Rules

- Prefer additive changes over renames or removals.
- Use explicit discriminators for unions and state machines.
- Return stable error codes with human-readable messages as secondary detail.
- Avoid making display text, log messages, or exception names part of the
  machine contract.
- Do not encode natural-language understanding as keyword maps in an API layer.
- Keep idempotency, pagination, sorting, filtering, and retry semantics explicit.
- Make ownership of defaults clear: server default, client default, or product
  default.

## Compatibility Review

Before changing an interface, answer:

- Which callers can break?
- Is the change backward compatible?
- Can old and new clients coexist?
- What happens to unknown enum values or event types?
- Is migration or deprecation required?

## Verification

Use contract tests or schema tests for:

- Valid request and response.
- Missing required fields.
- Unknown fields.
- Unknown enum or union variants.
- Error envelope shape.
- Version mismatch.
- Timeout and cancellation propagation.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HsienW](https://github.com/HsienW)
- **Source:** [HsienW/ai-agent-engineering-playbook](https://github.com/HsienW/ai-agent-engineering-playbook)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hsienw-ai-agent-engineering-playbook-api-and-interface-design
- Seller: https://agentstack.voostack.com/s/hsienw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.