Prepare for external API failure or change
An external API is a dependency: accessible documentation does not guarantee your application can use it. Plan what happens when responses are missing, late or structurally different.
Identify the dependency and its effects
List functions using the API, received data, permissions and the monitoring owner. Distinguish a catalogue describing a service from operational access actually obtained.
The official job-offers API record currently publishes a notice that it is no longer exposed on pole-emploi.io. This illustrates why a documentation URL alone cannot validate integration; it does not establish permanent closure.
Define a deadline and fallback
Choose a timeout compatible with the user’s task. On expiry, show a clear state: unavailable data, a dated previous result or deferred processing. Do not replace missing data with a plausible value.
Fictional example: an indicator comparison page can remain useful when it shows the last result date. It must not display “no vacancies” when the search service fails to respond.
Simulate errors in isolation
Prepare fictional responses: success, empty response, authorisation error, timeout and missing field. Compare display and logs with expected outcomes without multiplying calls to the real service.
For an action writing to another system, also simulate a lost response after execution. Recovery must check what actually happened before retrying, otherwise an operation may occur twice.
Separate freshness from availability
If results are retained, define what may be displayed, for how long and with which date. An old value may help a history view but mislead in an immediate situation.
Document data that must not be retained or is too sensitive, along with reuse permissions. A cache does not automatically authorise indefinite storage or republication.
Organise recovery and monitoring
Prepare proportionate reporting, an owner and a verification task after restoration. Check schema changes and pending records before declaring recovery complete.
Keep a manual procedure for essential functions. Monitoring must follow actual journey usefulness: a correct HTTP response may still contain unusable information.
A record to keep with the decision
| Item | Evidence |
|---|---|
| Dependency | Service, function, access and owner. |
| Fallback | Timeout, message and usable data. |
| Tests | Fictional cases and expected outcomes. |
| Recovery | Pending-task review and recovery evidence. |
Download the worksheet to fill in (CSV)
Frequently asked questions
Does HTTP 200 prove integration works?
No. Check contents, schema, permissions and business outcome.
Should every error be retried automatically?
Not without knowing the action and duplicate effects. Writes require particular care.
Reference material
France Travail · Avis de distribution de l’API Offres d’emploi
The practical checklist is an editorial synthesis to adapt to your service. It does not constitute a certification or an audit result.