How should we deprecate Stripe APIs? (~2016)

strategy (37), eng-strategy-book (25)

This is a work in progress draft.

Hi

This is an exploratory, draft chapter for a book on engineering strategy that I’m brainstorming in #eng-strategy-book. As such, some of the links go to other draft chapters, both published drafts and very early, unpublished drafts.

Reading this document

To apply this strategy, start at the top with Policy. To understand the thinking behind this strategy, read sections in reserve order, starting with Explore.

More detail on this structure in Making a readable Engineering Strategy document.

Policy & Operation

  • We never deprecate APIs without an unavoidable requirement to do so. Even if it’s technically expensive to maintain support.

    To provide a comparison point, scenarios where we would deprecate an API are things like the deprecation of TLS 1.2 which was obligated for PCI compliance, and the introduction of the [Payments Intents APIs to maintain compliance with Europe’s Strong Customer Authentication requirements. Note that even in the later case the preexisting Charges API was preserved.

  • Translation layer from old APIs to new APIs

  • We need to design APIs to support long lifetime

    TODO: What are some good examples?

  • All API changes, include deprecations, are approved by the API Review group

  • We will provide tooling to support API upgrades

  • We will aggressively support SDKs which give us a stronger mechanism to support upgrades

Diagnosis

  • API deprecation require significant our customers to make significant investments, and each of those investments is an opportunity to consider churning.
  • The longer an API integrate exists within a company, the more entrenched that integration becomes for that company.
  • …