Staff engineer · Principal engineer · Integration engineer
Understand the behavior before you rebuild the interface.
You have been asked to integrate with a platform you did not build, reconstruct an interface from partial documentation, or change code whose behavior nobody can fully describe. You need evidence, not a summary.
The questions you need answered.
- What does this system actually do when it receives this request?
- Which of these behaviors have been observed, and which are someone’s inference?
- What interfaces and dependencies exist that the documentation does not mention?
- How do I prove the client I generated matches the real thing?
- What breaks on our side when the upstream system changes?
Worth knowing first.
Observed is not verified
Seeing a response once tells you what happened once. A repeatable test tells you what the system does.
Documentation describes intent
The spec says what the system should do. Only the running system can tell you what it does. Treat the gap as findings, not as errors.
Conformance tests
A generated SDK is a claim about an interface. Tests that run against the real system are what make the claim hold.
Working an unknown interface.
Collect what the system says about itself
Docs, schemas, logs, existing clients, error messages. Record each as a source, not as truth.
Probe deliberately
Vary one thing at a time: fields, order, timing, auth. Note what you observed and what you only inferred.
Turn findings into tests
Each behavior you rely on becomes a repeatable test. Anything you cannot test stays labeled open.
Write the contract from the tests
The specification comes from what passed, not from the docs. Re-run the tests when the upstream changes.
Where Foundry fits.
Every finding carries its evidence state: verified, observed, inferred or open. How we work.
Reconstruct APIs
An OpenAPI specification built from how the system responds, with each behavior carrying its evidence state.
Generate SDKs and integration clients
Typed clients shipped with conformance tests that run against the real system.
Verify behavior
A test suite you can keep running, so the next person does not have to re-investigate.
Reading for your situation.
How to build an inventory of undocumented dependencies
A method for finding what a system calls, reads, writes and waits on, when nobody wrote it down, and for recording how sure you are about each item.
How to investigate an undocumented system without confusing inference with fact
A working method for learning what an undocumented system does, and for keeping what you saw separate from what you assumed.
How to preserve business behavior during modernization
How to find the behavior a legacy system's users depend on, decide what must survive a rewrite or migration, and prove afterwards that it did.
What a useful software behavior report should contain
The sections, evidence labels and level of detail that make a behavior report usable by engineers, not just readable by managers.
Next step.
Describe the interface or system. We tell you what a defined engagement would deliver.