Skip to content
ContractSpec
Start here

Core guide · Guides · 3 min read

Bind external services deliberately

Keep a feature's requirements separate from credentials, tenant connections and provider behavior.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

Separate requirement, connection and binding

An application can describe the capability it needs without embedding a provider account in its contract. The integration model distinguishes a service definition, a tenant's configured connection and the application binding that selects a connection for a named slot.

This separation makes configuration review possible: you can ask what the product needs, which connection supplies it and where that connection may be used.

1 / 4

0 points in your packet

Separate requirement, connection and binding

An application can describe the capability it needs without embedding a provider account in its contract. The integration model distinguishes a service definition, a tenant's configured connection and the application binding that selects a connection for a named slot.

This separation makes configuration review possible: you can ask what the product needs, which connection supplies it and where that connection may be used.

ConceptQuestion it answersKeep out of it
Integration definitionWhat capabilities does this provider integration expose?Tenant credentials
Tenant connectionWhich account and environment are configured?Unbounded permission inferred from an account name
Application bindingWhich slot uses which connection?An assumption that every workflow may use it
Host implementationHow is the actual effect executed?Secrets in browser-visible configuration

Make the host responsibilities concrete

Choose how the host resolves credentials, checks the selected connection and supplies the provider client. Keep secrets behind references or server-side access paths. Derive tenant context from the trusted identity boundary rather than treating an incoming tenant identifier as authority.

A capability declaration does not establish that credentials are valid, quotas are configured or a remote service is reachable. Those checks belong to the selected implementation and environment.

Progress from fixture to provider

Start with a fixture port to test the product behavior without external effects. Then run a provider-specific qualification in an appropriate test environment, including the relevant error, retry and duplicate-request cases.

Record which calls used real provider behavior. A deterministic local example can demonstrate your composition while leaving live service semantics untested.

Review a provider change as a behavior change

When changing a provider, compare supported capabilities, result semantics, rate behavior, idempotency and operational evidence. An adapter that satisfies a TypeScript interface can still behave differently in ways users notice.

Keep the application contract stable where that is intentional, and make any changed behavior visible through versioning, tests and documentation. Portability is achieved through those explicit seams.

Keep purpose, account and use separate.

A workflow needs to prepare a customer reply. Explore the record that answers each connection question.

What are you choosing?

A CONCRETE SITUATION

Name a capability without embedding an account.

The product needs a provider operation that can retrieve the relevant customer context.

01 / Purpose

Name the workflow and the information it needs.

What changes

An integration definition makes supported capabilities inspectable.

What stays explicit

Tenant credentials do not belong in the portable application requirement.

Follow the consequence

Choose the smallest useful operation. A definition does not establish that a selected account is configured or reachable.

Bind external services deliberately ↗

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.