# Api

> Use for REST API contracts: endpoints, fields, evolution, status codes, errors, pagination, idempotency.

- **Type:** Skill
- **Install:** `agentstack add skill-kreek-consult-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kreek](https://agentstack.voostack.com/s/kreek)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kreek](https://github.com/kreek)
- **Source:** https://github.com/kreek/consult/tree/main/consult/skills/api

## Install

```sh
agentstack add skill-kreek-consult-api
```

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

## About

# API

## Iron Law

`DESIGN THE CONTRACT FIRST. EVOLVE WITHOUT BREAKING. PICK STATUS BY ORIGIN.`

## When to Use

- Adding, removing, renaming, or reviewing REST endpoints, fields,
  status codes, webhooks, auth, pagination, rate limits, or
  idempotency.
- Writing or changing OpenAPI, JSON Schema, public SDK boundaries, or
  integration contracts external callers depend on.

## When NOT to Use

- Internal function signatures with no caller contract; use
  `domain-modeling` or `refactoring`.
- Auth, secrets, or trust-boundary review beyond API shape; use
  `security`.
- Database schema design; use `database`.
- Non-REST API styles (gRPC, GraphQL, message queues): contract,
  error, and evolution conventions differ; use `architecture` for
  style-of-API decisions and the relevant ecosystem's conventions for
  shape.

## Core Ideas

1. **Contract first.** Sketch OpenAPI or the repo's API contract source
   before controller code; implement *from* the contract, not toward it.
   Every response shape is explicit, including errors, empty states,
   pagination, and auth failures. Durable API interfaces route through
   `contract-first`; error shape is part of the contract.
2. **Evolution: additive in place; breaking needs a path forward.**
   Optional fields, query params, headers, methods, and endpoints
   evolve in place. Renames, removals, required additions, status-code
   changes, and semantic changes need a successor contract or
   deprecation path. Never break in place. See
   `references/api-evolution.md`.
3. **Versioning: one strategy per service.** Pick URL path, media
   type, header, or date and apply it consistently. Major bumps for
   breaking changes only; compatible additions never re-version.
   Retire versions with an overlap window; route deprecation
   primitives through `release`. See `references/api-evolution.md`.
4. **Errors: status by origin, shape by contract.** `4xx` for
   consumer-request problems, `5xx` for upstream or your-service
   problems; never mix origins in one response. Use the chosen data
   model's native error shape (JSON:API `errors[]`, FHIR
   `OperationOutcome`, or RFC 9457 Problem Details). These are
   structurally distinct conventions, not interchangeable. Never leak
   raw upstream or internal errors. See
   `references/rest-error-status-codes.md`.
5. **Default to JSON:API; switch only when the domain has its own
   standard.** JSON:API is the default for REST resource APIs (envelope
   with `id`/`type`/`attributes`/`relationships`, sparse fieldsets,
   includes, pagination conventions, error array). Switch to a
   domain-specific standard when one applies: FHIR for healthcare,
   HAL for hypermedia-centric APIs, JSON-LD when semantic-web interop
   matters. Document deviations from the chosen standard explicitly.
   See `references/data-models.md`.

## Workflow

1. Identify the caller and the contract surface they bind to.
2. Define the contract before implementation: path, method, request body,
   response bodies, status codes, auth, pagination, idempotency, and error
   shape.
3. Route durable API interfaces through `contract-first` before controller,
   client, SDK, webhook, or integration work continues.
4. Apply the relevant reference only when the feature needs it:
   `api-evolution`, `rest-error-status-codes`, `idempotency`, `pagination`,
   `webhooks`, or `middleware-vs-handler`.
5. Add outer-boundary contract or behavior tests. Update source-of-truth docs,
   not generated output by hand.

## Verification

- [ ] Contract exists or is updated before implementation lands.
- [ ] Durable API interfaces have explicit user approval before
      implementation continues.
- [ ] Every endpoint documents request, auth, responses by status, and errors.
- [ ] Request, response, and error shapes follow the chosen data model
      consistently; status codes are selected by origin and do not leak internal
      or upstream details.
- [ ] Non-idempotent mutations define idempotency key scope, replay window,
      duplicate response, and conflict semantics, or are documented as unsafe to
      retry.
- [ ] Lists and streams have bounded pagination, stable ordering, and explicit
      invalid-token behavior; bad tokens do not silently restart, rewind, or
      skip position.
- [ ] Additive changes are optional and old callers still work; incompatible
      changes have a successor contract or deprecation path with overlap and
      migration guidance.
- [ ] Webhooks are signed, timestamped, replay-protected, and
      deduplicable.
- [ ] Middleware is limited to transport-wide request-pipeline
      concerns; endpoint-specific validation, ownership checks,
      privileged authorisation, and domain invariants stay at the
      route/domain boundary.
- [ ] Tests exercise the public boundary; unproven public contract claims are
      reported.

## Tripwires

Use these when the shortcut thought appears:

- Treat field renames and removals as breaking unless a successor contract or
  deprecation path exists.
- Pick status by origin: consumer problems are `4xx`; service/upstream problems
  are `5xx`.
- Define response and error shape in the contract before returning handler
  internals.
- Define bounded pagination, stable ordering, and invalid-token behavior before
  the endpoint can grow.
- Define idempotency key scope, replay window, duplicate response, and conflict
  semantics before retrying mutations.
- Sign, timestamp, replay-protect, version, and deduplicate external webhooks.
- Keep route-specific validation, ownership, and domain rules in handler/domain
  code; use middleware for transport-wide concerns.

## Handoffs

- `contract-first`: durable API approval.
- `proof`: prove at the request → handler and handler → response handoffs;
  status codes, error envelopes, and pagination contracts are asserted at
  those seams.
- `error-handling`: internal failure mapping, remote-call timeouts, retries,
  budgets, and circuit breakers behind the API.
- `security`: authn/authz, input trust, SSRF, secrets, and data exposure.
- `architecture`: middleware placement and API style decisions.
- `async-systems`: SSE, subscriptions, event streams, async consumers, delivery.
- `release`: version bumps, changelog, `Sunset`, and `Deprecation` primitives.
- `documentation`: API docs location; generated contract reference stays source
  of truth.

## References

- `references/api-evolution.md`: evolution rules and versioning
  strategies.
- `references/rest-error-status-codes.md`: status-by-origin decision
  tree.
- `references/data-models.md`: JSON:API as the REST default; FHIR,
  HAL, JSON-LD when the domain calls for them.
- `references/idempotency.md`: idempotency-key contract.
- `references/pagination.md`: cursor and bounded-pagination semantics.
- `references/webhooks.md`: signing, versioning, replay protection.
- `references/middleware-vs-handler.md`: request-pipeline placement.
- `../security/references/web-app.md`: CSRF middleware, security
  headers, and CORS.
- `../security/references/api-and-auth.md`: handler-level
  authorisation caveats for privileged endpoints.

## Source & license

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

- **Author:** [kreek](https://github.com/kreek)
- **Source:** [kreek/consult](https://github.com/kreek/consult)
- **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-kreek-consult-api
- Seller: https://agentstack.voostack.com/s/kreek
- 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%.