Check a vendor API before promising a web-app integration

Start with one business exchange

Write the job in plain language: “When a repair job is approved, show the matching stock availability in our app and reserve a part only after a dispatcher confirms.” Name the source record, target record, direction of travel, maximum acceptable delay and person who resolves a mismatch. “Sync everything” gives no way to test whether a vendor supports the actual task.

List the exact operations the first release needs: read availability, create a reservation, learn when it changes and retrieve the records needed if the connection ends. Separate a capability the vendor documents from one this account and plan can use. The app’s own record model, user permissions and system-of-record rules belong in their dedicated decisions; this worksheet tests whether an external product can satisfy an agreed exchange.

Copy the integration evidence worksheet

Make one row per required operation, not one optimistic row for the whole vendor. Download the editable CSV above: it contains the column headings, an empty template row and four clearly fictional Example Parts rows. Keep the columns when replacing the example with your own operation. Give every row an owner and a dated evidence link or redacted test result. Never put customer records, credentials, raw tokens or full request logs in a shared worksheet.

Mark a row pass only when the chosen account or plan, current documentation and a safe representative test support the required operation. Unknown means a decision owner, access grant, provider answer or test is missing. Fail means the behavior is unavailable or cannot meet an agreed constraint. An unknown on a critical operation blocks an unconditional go; it is not a presumed pass.

• Business operation | Vendor, account, plan and documentation date | Endpoint or event and required fields | Authentication and minimum permissions | Read/write and record boundary | Volume, quota and pagination | Event or query availability | Sandbox and failure tests | Error, retry and reconciliation behavior | Export or exit route | Evidence link or redacted test result | Owner, status and decision.
• Business operation: describe one observable exchange and the person who needs its result. Write the maximum acceptable delay and what happens when the exchange cannot finish.
• Access: record who can grant the connection, which permissions are requested and actually granted, and whether read and write operations can be separated. Review the exact production plan, not a marketing feature list.
• Capacity and completeness: estimate ordinary and peak calls, record the provider’s applicable limits, and identify the continuation rule that gets past the first page of a collection.
• Change and recovery: name the needed event or supported query, its delivery or polling limits, how duplicates and missed updates are found, and the operator who resolves an uncertain state.
• Exit and evidence: name every record, field, attachment, relationship and history window needed later. Attach a safe test result that checks the required route rather than assuming an export button covers it.

Prove access and capacity against the real plan

List each endpoint and event separately. Record the authorization method, the smallest useful permissions, who can grant them and what revocation would interrupt. The OAuth security guidance and GitHub App permission documentation support narrowing token authority to the operations actually needed. If a browser-based app obtains OAuth authorization, assess the provider’s supported authorization-code and PKCE flow against the browser-app guidance; do not move a long-lived vendor secret into client JavaScript to make a prototype work.

Estimate normal and peak call volume from the planned user journey. Check the provider’s limits for the chosen account, endpoint and operation, then test the documented throttling response and recovery rule. GitHub documents primary and secondary REST limits, while Microsoft Graph documents variable limits and Retry-After handling. A universal “requests per minute” number would be misleading here. An accepted request in a quiet test account does not prove the planned peak will fit.

A successful first page does not prove complete collection access. Follow the actual provider continuation mechanism through a small representative set and confirm the final record arrives. GitHub REST documents Link-based pagination; Stripe’s API documents cursors and has_more. Record the continuation token or link only in an appropriately protected test log if it could expose data. Never hard-code one provider’s pagination method for another.

Test events, uncertainty and recovery

Record whether the required change is exposed through a webhook, change feed or supported query. Check the event types and fields, delivery authentication or signatures, a stable delivery identifier, duplicate behavior and the provider’s documented recovery window. GitHub’s webhook guidance covers secret validation and delivery IDs; its failed-delivery guidance explicitly says failed webhook deliveries are not automatically redelivered. Do not write “the provider will retry” without checking that provider and account.

An event arriving is not proof that the downstream write completed. Define what the operator sees when permission is revoked, the vendor times out, the response is uncertain, a request is throttled or the same event arrives twice. If a write may have succeeded before the connection failed, test how the app finds the resulting vendor record before retrying. This page establishes whether the chosen provider offers enough evidence and recovery access; the separate automation-failure guide covers running a workflow after launch.

Check the test space and the exit route

Use a vendor-supported sandbox or test account when one is available. Compare its permissions, event coverage, data shape and limits with the intended production plan, and record any gaps. Stripe’s sandbox documentation is a useful example of an isolated test environment with stated limitations; it is not evidence that every vendor supplies equivalent testing. Exercise a safe success, permission denial, documented failure simulation, duplicate event and interrupted collection without using live customer records.

Identify the exit route for every record the app will need if the connection ends: API collection, dashboard export, attachments, linked identifiers and the required history period. Stripe documents specific standard export categories and a customer-list API, which illustrates why “there is an export” does not prove that every needed object and relationship is portable. Test a representative export against the agreed inventory and record missing fields or retention constraints. This is a feasibility check, not a promise that a future migration will be effortless.

Hypothetical example: a repair app and parts service

Imagine an internal repair app connecting to Example Parts, a fictional vendor. This is an invented planning example, not a Kinetivy client, vendor integration or measured result. The business needs to read stock availability before dispatch and create a reservation only after a dispatcher confirms. Its owners require 12 months of reservation history for the agreed exit path. The downloadable worksheet fills all twelve columns for the four operations below.

Availability lookup is a hypothetical pass: the fictional plan lists a stock-read operation and read-only permission, and safe sandbox test I1 retrieves two known parts through the final cursor page. Reservation creation is a separate hypothetical pass: the fictional account grants a narrowly scoped reservation-create permission; test I2 submits only a dispatcher-approved sandbox part and quantity, reads back the new reservation ID and status, then confirms a caller without the grant is denied. Before repeating an uncertain write, test I2b queries the vendor using the approved request reference and verifies that a second reservation is not created. These are fictional example outcomes, not verified claims about a real API.

Reservation-status updates remain unknown: an event name appears in the fictional documentation, but the team has not proved cancellation or expiry coverage or replay after a missed delivery. The vendor administrator owns test I3: cause a sandbox expiry, interrupt the receiver, restore it and reconcile the final state. Until I3 passes, the app cannot promise current reservation status. Bulk history fails the hypothetical requirement: the fictional entry plan exposes only 30 days, while the approved exit requirement is 12 months. Test I4 confirms the earliest available record. These figures illustrate a conflict, not an actual vendor limit.

• I5 — Revoke the sandbox grant. The app must show that reconnecting is required and must not silently report a completed reservation.
• I6 — Use a documented rate-limit simulation. A delayed retry must respect the selected provider’s response and the agreed maximum delay.
• I7 — Repeat a reservation request after an uncertain response. Check the provider for an existing reservation before any retry so a second reservation is not created without explanation.
• Decision — The approved 12-month exit requirement currently fails, so the decision is no-go. A conditional go would require the owners to formally revise that requirement, document an alternative exit or retention path, exclude unverified live status from the first-release promise, and approve a useful bounded journey. Without those recorded changes, the team must not call the integration ready.

Make the decision explicit before build

Mark go only when every critical operation passes and named owners accept the documented limits. Use conditional go for a bounded first release only when missing capabilities are excluded from its user promise and the remaining journey works. Choose no-go when an essential read, write, event, permission, capacity or exit requirement fails. Record the decision date, vendor documentation version, account and plan, decision owner and trigger for re-review.

Turn the passed rows and negative tests into release acceptance cases. Recheck the vendor contract when its plan, API version, permissions or intended use changes. The worksheet does not replace a security review or the web app’s permission matrix; it gives the team a defensible answer to whether this particular external connection can be promised at all.