API INTEGRATION CONTRACT REVIEW
Original ShowMeYourSaaS teaching resource | 2026-10-27
AccountBook and HelpBench are fictional. The JSON contract defines an invented API.

COMPLETED EXAMPLE
Workflow: keep the support company name and plan aligned with the CRM.
Source of truth: AccountBook owns company_name, subscription_tier, record_version.
Destination: HelpBench owns ticket status and agent notes.
Stable external key: crm:{immutable account_id}.
Tenant authorization: verify the connection and destination belong to the requester.
Example destination path: PUT /v1/companies/crm-acct-041.
Success in this invented contract means stored and applied.
Lower source_version must not overwrite a higher stored version.
A repeated identical version causes no additional side effect.
A conflicting same-version body requires investigation.

MAPPING
account_id -> external_id with crm: prefix.
company_name -> trimmed, nonempty name.
subscription_tier -> plan; starter, team, enterprise are the supported values.
record_version -> positive integer source_version.
Support notes have no reverse mapping to the CRM.

SEVEN JSON CASES
1. Create a valid record, store version 7.
2. Repeat the identical version 7 without another side effect.
3. Apply version 8 over version 7.
4. Ignore version 6 when version 8 is stored.
5. Reject an empty company name.
6. Reject an unsupported plan.
7. A temporary failure leaves work incomplete and enters a bounded retry path.

REAL PROVIDER QUESTIONS
Business purpose / trigger / acceptable delay:
Source and destination owners for every field:
Authenticated user and permitted tenant:
Required access scopes:
Credential storage / rotation / revocation:
Documented method and actual endpoint:
Meaning of accepted versus applied:
Response schema and validation:
Pagination, cursor, and when it may advance:
Documented idempotency support and retention window:
Unknown outcome after a network interruption:
Ordering, duplicate deliveries, and conflicting updates:
Retry policy for documented transient errors and throttling:
Validation failures that must not retry unchanged:
Removal / deletion / retention rules:
Reconciliation source and cadence:
Safe operation IDs and error categories in logs:
Operator replay process and ownership:
Sandbox checks for account switching and cross-tenant attempts:
Rollback or disable path:
Review date:

BOUNDARY
An invented upsert contract does not establish a real provider's behavior.
Confirm current documentation and sandbox outcomes before implementing.
No API calls, live endpoints, credentials, or customer records are included.