Video summary

How to Stop Third-Party APIs From Ruining Your Code

Main summary

Key takeaways

Technology

Technological concept / problem

When integrating a third-party API (e.g., Stripe payments) directly into your code, you can end up with strong coupling to the vendor’s concepts and objects.

If your application logic (and many parts of the system) depend on Stripe-specific details—such as:

  • customer IDs
  • payment intents
  • metadata
  • confirmations
  • Stripe error classes

…then replacing Stripe (or upgrading it) becomes a large refactoring task.

The goal is to prevent external API design from “shaping” your architecture.

Proposed solution: Facade pattern as a boundary (not just a wrapper)

Use the Facade template to create a simplified interface for the rest of the application—specifically as a boundary that protects the domain layer.

Initial (incorrect) facade approach

Even after introducing a facade, if the facade method signatures and return values still expose Stripe objects (e.g., returning a payment intent), then callers must still understand:

  • Stripe-specific validation
  • Stripe-specific errors

Result: the Stripe dependency remains effectively present “above” the facade.

Correct facade approach (boundary-focused)

  1. Introduce a domain-facing protocol/interface (e.g., payment protocol).
  2. Ensure its methods return a payment result object that is not Stripe-specific.
  3. Implement the protocol in a Stripe-specific service (e.g., “Stripe gateway” + “payment service”).
  4. Higher-level business logic calls the protocol and deals only with:
    • domain-level inputs (order, payment method)
    • domain-level outputs (payment result)
    • domain-level terminology (no payment intents or Stripe models in business logic)

This keeps Stripe as a contained subsystem and leaves the domain clean.

Examples / references mentioned

  • An examples repository linked in the video description, including:
    • the code
    • a small test script that runs multiple sample orders
  • A testing approach using a dummy/mock Stripe implementation that conforms to the same facade/protocol interface.

Testing and maintainability benefits

If the facade is implemented properly—especially with errors and response objects mapped into domain types:

  • Testing becomes easier, because you can replace the facade implementation with mocks/dummies.
  • The speaker notes that running pytest succeeds with the dummy Stripe.
  • AI can help generate tests, reducing effort.

Common facade mistakes to avoid (explicitly listed)

  1. Pass-through wrapper A facade that just forwards Stripe operations (e.g., “create/confirm/cancel payment intent”) without simplifying domain concepts.

  2. God facade One large facade handling too much (payments + invoices + subscriptions + coupons, etc.). Prefer splitting into coherent services.

  3. Hiding important behavior Don’t obscure facts that callers need (e.g., whether payments are synchronous). Don’t hide requirements like client authentication if it matters to the caller.

  4. (Conceptual confusion) Facade vs Adapter

    • Adapter converts one interface to another (interface translation).
    • Facade simplifies access to a complex subsystem and decides what operations/data/errors/terminology cross the boundary.

Broader guidance beyond Stripe

The same pattern applies to other third-party integrations:

  • Weather APIs: wrap raw responses into domain objects.
  • Graphics engines (e.g., Pygame): don’t leak engine-specific vector/rectangle types into the domain model.
  • ORMS (e.g., SQLAlchemy): don’t pass ORM models through the business layer.
  • AI APIs (e.g., OpenAI/Anthropic): extract what you need and return domain-friendly objects so provider response types don’t spread through the app.

Main speakers / sources

  • Speaker: Arne (referred to as “arne.codes” / “Arne” in the program link and channel context)
  • Source concept: Design pattern discussion focused on the Facade pattern, including comparisons to Adapter.

Original video