Use and Re-use
API Description Languages and the Design Lifecycle
Slide 2
Slide 2 text
It’s All About…
• Structured Data
• API Semantics, Metadata, Protocols, and
Annotation
• Tooling
Slide 3
Slide 3 text
Design Lifecycle
• Design First (?)
• Collaborative Prototyping (realtime mocking)
• Automated Design and Style Validation
• Code Generation
• Parallel Client/Server Implementation with TDD/BDD/CI
• Interactive Documentation (validated in CI)
• Monitoring and Discovery
Slide 4
Slide 4 text
API Evolvability
Slide 5
Slide 5 text
Traditionally
Design and Consume
APIs around
Implementation Details
Slide 6
Slide 6 text
No content
Slide 7
Slide 7 text
No content
Slide 8
Slide 8 text
What if we could …
• Change implementation details
• Add new features
• Remove features
• Move fast
And not break things!
Slide 9
Slide 9 text
Hyperdrive
Slide 10
Slide 10 text
Representor Pattern
Slide 11
Slide 11 text
Teach Clients the
Semantic Meaning of a
Domain
Slide 12
Slide 12 text
Don’t Hard-code
Implementation Details
Slide 13
Slide 13 text
hyperdrive(apiary: “pollsapi")
hyperdrive(blueprint: “https://polls.apiblueprint.org/")
hyperdrive.enter("https://polls.apiblueprint.org/") { result in
// Explore API feature availability
}
Slide 14
Slide 14 text
if let questions = representor.transitions["questions"] {
// The API offered us a link to questions
} else {
// Gracefully handle when this feature is missing
}
Slide 15
Slide 15 text
if let create = representor.transitions["create"] {
// API supports creation
} else {
// Feature is missing
// Let's not show the create button in our UI
}
Slide 16
Slide 16 text
Demo
Slide 17
Slide 17 text
https://github.com/the-hypermedia-project/Hyperdrive
https://github.com/apiaryio/polls-app
https://github.com/apiaryio/polls-api
https://github.com/the-hypermedia-project/representor-swift
http://cocoadocs.org/docsets/Representor/0.5.0/
Mark W. Foster
[email protected]
@fosrias