Compare API Integrations

One Interface, Four Integrations

The direct API, Amazon Bedrock, Google Cloud's Vertex AI, and Microsoft Foundry all present Claude through the Messages API, and the request you write looks much the same on each. The differences sit at the edges: how the client is created, how identifiers are named, how credentials are found, which parameters are accepted, and which features have arrived. Lesson 165 chose a platform. This lesson looks closely at what the choice means for the code, so that the integration is correct on the platform chosen and portable if the choice changes.

The useful method is to compare the integrations along a fixed set of dimensions, record the answers with their sources and dates, and turn the result into a list of gaps the application must handle. The comparison is most valuable when it is written down, because the platforms' documentation changes, and an answer that was true last quarter may not be true now.

The Dimensions of Comparison

Five dimensions cover most of the differences between integrations:

The first two dimensions cause failures that are easy to see, because the request is rejected immediately. The feature dimension causes failures that are harder to see, because a feature may be missing and the application may fall back silently. That is why features get a gap analysis of their own.

Recording Features as Data

A comparison is most useful when it is data rather than prose. A small matrix that lists the features the application needs, and the platforms that provide each one, can be checked by code, and the check can be rerun when the documentation changes. The matrix below is an example with invented entries. The values for a real project must be taken from each platform's current feature table, with the date recorded beside them.

"""integration_gaps.py: find which required features each integration lacks."""

REQUIRED = {"messages", "tools", "streaming", "citations", "batches"}

# EXAMPLE VALUES ONLY. Replace each set with the current feature table for that platform.
MATRIX = {
    "direct": {"messages", "tools", "streaming", "citations", "batches"},
    "bedrock": {"messages", "tools", "streaming", "citations"},
    "vertex": {"messages", "tools", "streaming"},
    "foundry": {"messages", "tools", "streaming", "citations", "batches"},
}


def gap_analysis(required: set[str], matrix: dict[str, set[str]]) -> dict[str, list[str]]:
    return {platform: sorted(required - features) for platform, features in matrix.items()}


if __name__ == "__main__":
    for platform, missing in gap_analysis(REQUIRED, MATRIX).items():
        print(f"{platform}: {', '.join(missing) or 'none missing'}")

Output (with the example values above):

direct: none missing
bedrock: batches
vertex: batches, citations
foundry: none missing

How It Works

1. The required set is written down first, from the application's own needs. The comparison starts from what the application must do, not from what a platform offers.
2. Each platform's features are recorded as a set, so set subtraction gives exactly the features that are missing, with no duplicates or ordering issues.
3. The gap list is sorted, which makes the output stable, so a changed result shows up as a real change rather than a reordering.
4. The example values are labeled as examples. A matrix with invented entries is only a demonstration of the mechanism, and it must never be used as a source of truth. Its numbers belong to the illustration, not to any platform.
5. A gap is a decision point. Each missing feature must be handled: the platform is excluded for that feature, the feature is implemented another way, or the requirement is reconsidered.

Reconciling Request Shapes

Beyond features, the request itself can differ. A parameter accepted by the direct API may be rejected on one cloud, or a field may be named differently. The safest way to find these differences is to run the same request through each integration in a test environment, and compare the outcomes. The request that works on all of them is the portable core, and any request that works only on one should be isolated behind an adapter that the rest of the application does not see.

An adapter is a small layer that takes the application's request, applies the platform's identifiers and any parameter changes, and returns the request the platform expects. Keeping adapters at the edge means the application's logic stays the same across platforms, and only the adapter changes when the platform does.

Comparing Errors

Errors need the same attention, because they are how the application learns that something is wrong. The SDK maps errors into shared classes (Lesson 141), and a cloud integration may return failures that map onto different situations: an identity that lacks permission, a model that is not enabled in the account, or a quota that has been reached. The error handling in Lesson 168 covers these in detail. For the comparison, the question is whether each integration's failures map to the same handling, and where they do not, the difference must be written down and handled.

Keeping the Comparison Current

Platform documentation changes often, and features move from preview to general availability, or are removed. A comparison that is not reviewed becomes wrong without anyone noticing. A practical habit is to attach the date and the source to every entry in the matrix, and to rerun the comparison when a platform announces changes, and before each major release of the application.

Summary

The four integrations share an interface and differ at the edges: client setup, identifiers, credentials, features, and errors. Comparing them along fixed dimensions, and recording the features as data, turns the comparison into a gap analysis the code can check. Request differences are handled by adapters at the edge of the application. The matrix in this lesson is illustrative, and a real one must come from each platform's current documentation, with dates. The next lesson turns to the configuration of the clients themselves.