What's next for API Specifications

1. the future of API speci
f
ications
aidan 2021
alt: let’s be awesome

2. What is OpenAPI? Speci
f
ication? Are they ‘working’

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”

5. APIs Speci
f
ication are the API for our APIs
shouldn’t we treat them that way?

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…

8. Complexity is in the wrong place

9. Choose One

10. How do you make something evolvable?
invert that question….
what stops something from being evolvable?

11. FRICTION — remove the friction

12. Human Machine
Readable
Writable
⁃ “that’s a big change for vendors”
⁃ “that’s too much to ask of developers”
⁃ “that will break our company’s internal tooling”

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

16. DEMO

17. helpout — let’s start laying the foundation