Skip to content

Instantly share code, notes, and snippets.

@steverice

steverice/approval-process.md

Created October 11, 2016 04:20
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save steverice/2109c70ecff5b71d8bc0a072760b03fe to your computer and use it in GitHub Desktop.
Save steverice/2109c70ecff5b71d8bc0a072760b03fe to your computer and use it in GitHub Desktop.
Download ZIP
The API Approval Process at PagerDuty
Raw
approval-process.md

The API Approval Process

When do I need approval for an API change?

Approval is needed before shipping any change used by one or more wild clients or releasing the API for general availability. In other words, the API must be contracted.

If you are working on a prototype API, you may ship your code at will, but you acknowledge the following tradeoffs:

  • you are responsible to make any and all code changes to satisfy the final approved proposal before general availability
    • in other words, there will be additional churn
  • you have communicated to any clients of the prototype API that their integration may break at any time
  • your prototype is not making any breaking changes to existing contracted APIs

What constitutes approval?

An API is not approved until it's been merged into the Captain's Log.

Wild Clients

Any client that PagerDuty cannot, at a whim, revoke or modify without customer impact, is a "wild client". These clients are outside PagerDuty's control. These include:

  • Mobile apps that have been shipped to a public app store
  • Clients or client libraries written by third parties based on our published documentation
  • Client libraries that have been written and released by PagerDuty

Managed Clients

Any client whose distribution is controlled entirely by PagerDuty is a "managed client". This control includes the ability to stop users of the client from being able to use it at any time.

Clients that are under PagerDuty's control include:

However, you should still expect to modify managed clients if you're making a change to an API change they depend upon — otherwise the client will break!

Contracted APIs

A "contracted" API is one that may have already been in use, for any time, by a wild client. Once an API is "contracted", PagerDuty must continue to provide API functionality that implements the agreed-upon interface prior to any formal deprecation or removal process.

General Availability

"General Availability" refers to an API that is documented and is available to an unbounded number of users. It is not part of a beta or test program. An API whose use is gated on some unbounded criteria (such as pricing plan, number of users, allowed format, etc) is still generally available.

While not all contracted APIs are generally available, all generally available APIs are contracted.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment