3. Our APIs…
• Evolvable
• new features can be added, without breaking consumers
• Users can update on their own pace
• Approachable
• learnable
• easy to understand
• consistent
• Useful
• Meets its use cases
• API Calls map closely to use case / objective
4. Our APIs Speci
f
ications
• 🚨 Evolvable
• We make breaking changes to the API speci
f
ications when we add new features
• Many teams still using Swagger 2.0
• More users are asking vendors to support older version than newer versions
• 🚨 Approachable
• Most developers don’t use the specs, Optic built a whole business to capture this non consumption
• We don’t ‘read’ specs’ we don’t think spec. We think in examples
• 🚨 Useful
• Mileage varies
• Vendors struggle to support even the most basic use cases uniformly
• Where is universal support for “validation”?
• A lot of teams that use specs at scale have to build tooling around what should be common cases
“changelogs” “governance” “validation”
6. code generation validation documentation test generation
changelogs analytics collaborative-API design goverence
the
f
irst-decision was to use a docs tool (Swagger) for **everything
7. Use cases aren’t supported from the
f
irst-decision
• Design Use Cases
• lifecycle status (deployed, designed, partially-implemented?)
• Not mergeable / forkable
• Governance Use Cases
• can not support forward-only governance, linting noise
• Changelogs
• history is not part of the spec
• Validation
• inconsistent behavior across cloud providers, ‘di
ff
’ but no ‘patch'
• Di
ff
erent Protocols or Styles (not HTTP)
• hypermedia, event-driven APIs, GraphQL, gRPC, whatever comes next…
13. spectacle
a proposal to create a unified and stable foundation for
the API tooling space — one that allows more vendors to
easily support core use cases, for toolmakers to evolve and
experiment with new kinds of specifications, and for the
space as a whole to deliver more value to developers and
their teams.
14. make API specs like APIs
what if instead of giant YAML files, specs were
more like APIs?
…there are different queries, optimized for each use case
…and mutations you call when the API changes
vendors use the API too! with the same reference
implementation
15. facts and questions
(mutations) and (queries)
Machine Interfaces (queries) -> Human Interfaces
Human Interfaces -> Mutations -> Facts
/documentation
/generation
/validation
/governance