ometere123/the-skills-bible/api-sandbox-mock-engineer

API Sandbox and Mock Engineer

Purpose

Build and operate consumer testing without production effects while preserving enough behavioural fidelity for integration decisions.

Use this skill when

• Design safe test environments, mock servers, fixtures, simulators, fault injection, and fidelity documentation for API consumers.
• Independent producers and consumers need an explicit, supported contract.
• Interface behaviour must remain reliable across versions, failures, and organisational boundaries.
• Developer experience and operational evidence are part of the delivery outcome.

Do not use this skill as the primary workflow when

• The work is entirely internal to one module with no independent consumer contract.
• A previously defined generic architecture or security workflow is the dominant task.
• The requested change cannot be authorised, observed, or supported through its lifecycle.

Required inputs

• Consumer workflows, constraints, and expected outcomes.
• Current specifications, schemas, examples, SDKs, and implementation behaviour.
• Identity, tenant, data, permission, and secret requirements.
• Workload, payload, latency, quota, and dependency limits.
• Supported versions, release policy, incidents, and consumer inventory.

Classify missing information as blocking, important, or optional. Inspect the actual specifications, code, gateway policies, SDKs, credentials, usage, delivery evidence, and support history before asking for information that can be verified directly.

Core operating principles

• Design interfaces around stable consumer outcomes rather than internal implementation structure.
• Treat schemas, examples, documentation, SDKs, policies, and compatibility rules as versioned production artefacts.
• Prefer explicit contracts, deterministic validation, idempotent effects, and bounded failure semantics.
• Keep identity, tenant, permission, quota, and ownership decisions authoritative and server-enforced.
• Preserve backward compatibility deliberately and make breaking changes visible, testable, and migratable.
• Design retries, timeouts, cancellation, pagination, ordering, and partial failure as part of the public contract.
• Protect consumers from implementation churn while avoiding abstractions that hide important differences.
• Make integrations observable end to end through stable identifiers, correlation, delivery state, and reconciliation.
• Provide realistic examples, sandboxes, diagnostics, and migration guidance so consumers can succeed independently.
• Govern the full lifecycle from discovery and onboarding through change, deprecation, offboarding, and retirement.

Workflow

1. Define the consumer outcome

• State the required outcome for consumer testing without production effects while preserving enough behavioural fidelity for integration decisions.
• Identify unacceptable ambiguity, side effects, and consumer failure.

2. Map actors and trust boundaries

• Map application developers, partner testers, SDK teams, API providers, quality engineers, and support.
• Assign provider, consumer, platform, security, support, and decision ownership.

3. Define the public contract

• Specify test operations, fixtures, scenarios, deterministic state, simulated time, errors, limits, callbacks, and reset.
• Separate public semantics from internal implementation and document authoritative behaviour.

4. Secure identity and data

• Design synthetic identities, fake data, isolated credentials, destination sinks, secret separation, and production boundary controls.
• Validate every trust decision at the authoritative boundary and minimise exposed data.

5. Engineer reliability

• Define simulated timeout, rate limit, dependency failure, partial success, webhook retry, reset, and environment outage.
• Make partial success, unknown outcomes, cancellation, and recovery visible to consumers.

6. Bound scalability and cost

• Control concurrent testers, fixture namespaces, data reset, callback volume, payload bounds, and sandbox capacity.
• Set explicit limits, fair-use rules, capacity assumptions, and dependency protections.

7. Design developer experience

• Provide instant onboarding, discoverable scenarios, test credentials, request inspection, replay, and clear fidelity notes.
• Ensure a new consumer can complete the critical workflow without undocumented support knowledge.

8. Validate compatibility

• Test contract parity, versioned fixtures, SDK compatibility, behaviour differences, and coordinated production changes.
• Use supported consumers, generated clients, contract fixtures, and mixed-version scenarios.

9. Instrument operations

• Observe scenario use, mismatch reports, failed tests, environment health, resets, version drift, and support feedback.
• Correlate consumer-visible failures with provider, dependency, contract, and release evidence.

10. Govern the lifecycle

• Define publication, ownership, support, change review, deprecation, offboarding, and retirement.
• Record residual risks, exceptions, migration deadlines, and review triggers.

Decision rules

Required outputs

• Consumer outcome and scope.
• Actor, ownership, and trust map.
• Versioned interface or integration contract.
• Identity, permission, and data controls.
• Reliability and recovery semantics.
• Limits, capacity, and fairness policy.
• Developer onboarding and diagnostic assets.
• Compatibility and migration evidence.
• Operational telemetry and support model.
• Lifecycle, exception, and retirement record.

API, SDK, and integration quality gates

• Consumer gate: Target consumers, workflows, constraints, and success outcomes are explicit.
• Contract gate: Inputs, outputs, errors, state changes, ordering, retries, and limits are precise.
• Identity gate: Authentication, authorisation, tenant, delegation, and credential lifecycle are enforced.
• Compatibility gate: Supported versions, additive changes, breaking changes, and migration paths are documented and tested.
• Reliability gate: Timeouts, idempotency, retries, partial failure, reconciliation, and degraded behaviour are operational.
• Security gate: Untrusted inputs, callbacks, secrets, permissions, and third-party data are bounded.
• Developer gate: Documentation, examples, diagnostics, sandbox behaviour, and SDK ergonomics support independent adoption.
• Observability gate: Requests, deliveries, retries, transformations, failures, and partner outcomes are traceable.
• Scalability gate: Quotas, pagination, payload limits, batching, concurrency, and dependency ceilings are explicit.
• Lifecycle gate: Onboarding, change, deprecation, offboarding, data deletion, and retirement have accountable owners.

Evidence standard

For consequential conclusions, identify the exact API or protocol version, schema, SDK version, environment, consumer, identity, tenant, payload, dependency state, request or delivery identifier, and time window. Distinguish observed contract behaviour, supported inference, and undocumented assumptions. Do not claim compatibility from schema comparison alone when semantics or side effects differ.

Failure handling and escalation

Pause or escalate when:

• The authoritative contract, owner, or consumer expectation is unclear.
• Credentials, tenant boundaries, permissions, callback destinations, or data rights cannot be verified.
• Retrying may duplicate money movement, messages, records, or other external side effects.
• A breaking change affects unknown or uncontactable consumers.
• Third-party behaviour conflicts with documented guarantees or creates active data loss.
• Production testing could send real communications, incur charges, or affect external users.
• Residual integration, security, privacy, or operational risk exceeds delegated authority.

Report the exact blocker, verified state, affected consumers, evidence, safe options, and smallest required decision.

Common anti-patterns

• Sandbox sharing production credentials.
• Mock always returning happy paths.
• Undocumented differences from production.
• Fixtures containing real customer data.
• One shared mutable test account.
• Mocks updated after production changes without compatibility tests.

Completion checklist

• [ ] Consumer outcomes and exclusions are explicit.
• [ ] Provider and consumer ownership is recorded.
• [ ] The contract includes failure and side-effect semantics.
• [ ] Identity, tenant, and data boundaries are enforced.
• [ ] Retries, timeouts, and unknown outcomes are safe.
• [ ] Limits and dependency ceilings are explicit.
• [ ] Independent consumers can integrate from published assets.
• [ ] Supported versions pass compatibility tests.
• [ ] Operations can correlate and reconcile failures.
• [ ] Deprecation and retirement are executable.

Interface and integration record

# Interface and Integration Record
 
## Outcome
[Consumer workflow, partner exchange, SDK use case, or integration result]
 
## Scope
[Providers, consumers, environments, identities, tenants, data, and exclusions]
 
## Contract
[Operations, schemas, errors, ordering, pagination, quotas, and side effects]
 
## Compatibility
[Versions, supported clients, additive rules, breaking changes, and migration]
 
## Reliability
[Timeouts, retries, idempotency, delivery, reconciliation, and recovery]
 
## Security and privacy
[Credentials, permissions, validation, secrets, callbacks, and data lifecycle]
 
## Developer experience
[Documentation, examples, SDKs, sandbox, diagnostics, and support]
 
## Observability
[Identifiers, traces, logs, metrics, dashboards, and partner evidence]
 
## Residual risk
[Known limitations, owner, acceptance, expiry, and communication]
 
## Lifecycle
[Rollout, deprecation, offboarding, deletion, and retirement]

Related skills

• api-documentation-engineer
• developer-portal-engineer
• contract-testing-engineer
• test-environment-engineer

Maintenance rules

Review this skill when consumers, schemas, protocols, providers, SDKs, limits, regulations, or operational dependencies change; incidents reveal missing contract behaviour; the workflow becomes tied to one vendor; the file approaches 500 lines; or reusable schemas, examples, validators, fixtures, or compatibility tests would improve execution.