Skip to content

Instantly share code, notes, and snippets.

@steverice

steverice/v2-vision-sample.md

Created October 8, 2016 02:11
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/e33e5d401e5f8fa9e260ba1b7a20bdd2 to your computer and use it in GitHub Desktop.
Save steverice/e33e5d401e5f8fa9e260ba1b7a20bdd2 to your computer and use it in GitHub Desktop.
Download ZIP
Snippet of PagerDuty API v2 Vision
Raw
v2-vision-sample.md

API v2 Vision 👓

This document outlines the vision and scope for v2 of the API.

Ordered lists represent prioritized order. We recannot accomplish everything at once, and thus everything needs to be prioritized sooner or later. I choose sooner.

This document does not attempt to present a comprehensive record of all the changes that will be made, as those will be captured by stories in JIRA. Instead, it establishes the goals, principles, and patterns that we'll use to make the decisions about what needs to change.

It is a living document and will evolve as we discover new edge cases and outliers that weren't previously considered.

Goals

What are we trying to accomplish with API v2?

These are the high-level goals, in priority order:

  1. iteration
  • leave well enough alone
  1. adoption
  • prove the effectiveness of our versioning strategy
  1. consistency
  • provide consistency across endpoints
  1. performance
  1. semantics
  • better use of generic HTTP libraries and patterns
  • remove backwards-compatibility shims that lack semantic meaning
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment