Integrate external APIs securely: check responses, failures and data

Record a narrow integration contract

Start with a concrete operation, such as retrieving shipment status for your own order. Record target service, operation, permitted data, required permissions and responsible operator. Keep the target address in controlled configuration. A user-supplied host should not casually become a backend destination; arbitrary destination choice requires dedicated SSRF protection.

Separate tasks even within a trusted service. A key that can read shipment status need not also create shipments or export customer data. Use separate test and production credentials and a controlled key lifecycle.

The contract record should name the partner API version and possible deprecations. Clarify whether success means immediate completion or only job acceptance. Documentation containing the word ‘success’ does not replace this decision.

OWASP identifies excessive trust in external APIs as a distinct risk. Partner origin does not remove size, structure or security checks. OWASP API10:2023.

Check a response in several stages

First the transport contract must fit: expected destination, working certificate verification and a response within the defined budget. The TLS guide explains shared foundations. Do not disable certificate verification to apparently repair a failing integration.

Next come status, content type, bounded reading and data structure. A 200 may contain a business error; a 202 often confirms only acceptance. The partner's contract must specify which statuses represent which states. An HTML outage page is not simply an empty valid JSON response.

A synthetic response excerpt might be:

{
  "shipment_id": "demo-shipment-42",
  "client_reference": "demo-order-17",
  "state": "in_transit",
  "parcel_count": 2
}

A parser can establish that this is valid JSON. Meaningful use also requires checking that fields have agreed types and limits, the reference belongs to your requested order, and the shipment maps internally to the correct tenant. A freely supplied ‘tenant’ field would not replace that internal association.

Input validation explains these boundaries at your own API ingress. Partner responses have the same trust boundary elsewhere. Decide deliberately on extra fields: a contract may allow ignoring unknown optional fields. This differs from executing new state values or privileged instructions unchecked.

Limit time, size and concurrent work

A partner outage must not occupy every available execution slot in your API. Define a total time budget and, where supported by your client, suitable connection and response sublimits. Bound data while reading, before a complete large body occupies memory. Account for compressed responses and the maximum number of concurrent operations.

Exact values follow the function. An interactive status display may say ‘currently unavailable’ after a clear deadline. An important background job may instead be durably stored and processed later. An unlimited queue solves neither problem.

Assign retries to one responsible layer. If SDK, gateway and your code each retry several times, delays and load grow. A shared budget limits this behaviour. Microsoft: Retry pattern.

For writes, a locally aborted request also does not undo a possible effect at the partner. The retries and idempotency guide explains recognising the same job or resolving its outcome.

Send data selectively and control redirects

Send only fields needed for the agreed operation. Do not pass the entire internal customer object merely because it is convenient to serialise. A status query needs the partner reference and required credentials, for example; internal notes or other customer relationships normally do not belong.

Check whether and how the HTTP client follows redirects. Redirecting to another host may affect sensitive payloads, not just an Authorization header. For a fixed partner API, unexpected redirects may indicate configuration errors or contract changes. Stopping and investigating is then a sensible default.

Also watch for responses supplying new URLs for later steps. These are inputs to your fetching path again. A partner-supplied download address needs an appropriate destination policy; it must not open arbitrary internal destinations unchecked. This also applies to a compromised or misconfigured partner.

Choose a safe fallback state

A fallback is an explicitly designed alternative path. It must invent no permission and represent no uncertain write as completed.

Cached data must match identity, tenant and permitted use. One cache entry for different customers may mix confidential results. The Cache-Control guide covers HTTP foundations; application-level association remains an additional responsibility.

Test integration with a simulated partner

First build a small local stub, a controlled substitute for partner responses. Use fictional orders only. It need not recreate the entire external product: normal response, invalid structure, unexpected status, wrong reference, oversized data, delay and an uncertain outcome after an accepted action suffice for your contract.

Check that rejected responses trigger no business follow-up action. Evidence is your application's stored state and, where applicable, the number of executed dummy actions. A suitable error message alone says too little.

Before switching version or key, compare the same contract cases through the new path. Prepare configuration rollback and retain traceability of open jobs. Returning to an older API version requires it still to be supported and suitable for the affected data; a deliberately retired unsafe variant should not silently reactivate.

The JSON example is synthetic; no real partner or production credential was used. The API Security Check tests neither your outbound client nor business use of external responses. Inventory and versioning keeps the dependency current; logging and monitoring connects contract errors to an accountable response.

Next steps