Achieving API Awesomeness

API Days Zürich 2017 [http://www.apidays.io/events/zurich-2017]

Erik Wilde (@dret), API Academy, CA Technologies
September 26, 2017

[http://creativecommons.org/licenses/by/3.0/]

This work is licensed under a CC
Attribution 3.0 Unported License [http://creativecommons.org/licenses/by/3.0/]

Contents Erik Wilde (@dret): Achieving API Awesomeness

Contents

1 Introduction
- 3About Me
- 4API Academy [http://www.apiacademy.co/]
- 5Microservice Architecture
2 Awesome APIs
- 7API Excellence
- 8Excellence as a Service (EaaS)
- 9Web Culture: Webby Service Design
- 10APIs and API Landscapes
- 11API Stylebook: Error Format
- 12Excellent API Management → Awesome APIs
3 Interface ≠ Implementation
- 14Design and Constraints
- 15APIs are Interfaces
- 16Changing Culture
- 17A Microservices Landscape
4 Example: API Change Management
- 19API Change Management in API Strategy
- 20HTTP Sunset: An Even Simpler Example
- 21Capability Sedimentation
5 Conclusions
- 23DevOps Your APIs!
- 24Thanks! Q&A

Introduction

Outline (Introduction)

Introduction [3]
Awesome APIs [6]
Interface ≠ Implementation [4]
Example: API Change Management [3]
Conclusions [2]

Introduction Erik Wilde (@dret): Achieving API Awesomeness

(3) About Me

Ph.D. in Communications Systems [http://dret.net/netdret/publications#wil97b] from ETH Zürich [http://www.ethz.ch/]
Working on Web Architecture after writing the first Web Technology book [http://dret.net/netdret/publications#wil98]
UC Berkeley (2006-2011), working on Service Models for Open Government [http://dret.net/netdret/publications#wil09g]
EMC (2011-2014), working on transforming software products into service platforms
Siemens (2014-2015), working on using IoT to build WoT (APIs for Things)
Joined CA [http://www.ca.com/]'s API Academy [http://www.apiacademy.co/] in 2016 and now all about API Strategy and Design
Active in the usual places such as Twitter [http://twitter.com/dret], GitHub [http://github.com/dret], my blog [http://dret.typepad.com/dretblog/], LinkedIn [http://www.linkedin.com/in/netdret], and flickr [https://www.flickr.com/photos/dret/]

Introduction Erik Wilde (@dret): Achieving API Awesomeness

(4) API Academy [http://www.apiacademy.co/]

API Academy

Global Team working on API Strategy and Design topics
- Matt McLarty [http://www.apiacademy.co/team_member/matt-mclarty/] (Vancouver)
- Mike Amundsen [http://www.apiacademy.co/team_member/mike-amundsen/] (Cincinnati)
- Ronnie Mitra [http://www.apiacademy.co/team_member/ronnie-mitra/] (London)
- Erik Wilde [http://www.apiacademy.co/team_member/erik-wilde/] (Zürich/Berkeley)
Evangelizing ideas and technologies
- Speaking (conferences, events)
- Teaching (workshops, bootcamps)
- Publishing (blogs, articles, books, podcasts [https://soundcloud.com/user-426834320])
- Doing (side projects on API-related topics)
- Standardizing (participating in specification work)

Introduction Erik Wilde (@dret): Achieving API Awesomeness

(5) Microservice Architecture

Microservice Architecture: Aligning Principles, Practices, and Culture

Microservice Architecture: Aligning Principles, Practices, and Culture
Authored by [http://www.apiacademy.co/microservice-architecture-the-oreilly-book/] API Academy [http://www.apiacademy.co/] members Irakli Nadareishvili, Ronnie Mitra, Matt McLarty, and Mike Amundsen
- Get free electronic version courtesy of CA Technologies [http://transform.ca.com/API-microservice-architecture-oreilly-book.html]
- Get a hardcopy version [http://shop.oreilly.com/product/0636920050308.do]

Awesome APIs

Outline (Awesome APIs)

Introduction [3]
Awesome APIs [6]
Interface ≠ Implementation [4]
Example: API Change Management [3]
Conclusions [2]

Awesome APIs Erik Wilde (@dret): Achieving API Awesomeness

(7) API Excellence

Digital McKinsey: "What it really takes to capture the value of APIs" by Keerthi Iyengar, Somesh Khanna, Srinivas Ramadath, and Daniel Stephens; September 2017

Awesome APIs Erik Wilde (@dret): Achieving API Awesomeness

(8) Excellence as a Service (EaaS)

What matters for an API Center of Excellence (CoE)?
- Should excellence sit in CoE and be created/managed/delivered from there?
- Should the CoE be a service to enable all teams achieving excellence?
API landscapes are ecosystems that need cultivation
- Ecosystems value diversity to improve fitness and adaptivity
- Cultivation is a continuous process of feedback and improvement
Culture evolves over time as a set of shared practices
- Culture is a set of shared do and don't rules

Awesome APIs Erik Wilde (@dret): Achieving API Awesomeness

(9) Web Culture: Webby Service Design

Webby Amazon

Awesome APIs Erik Wilde (@dret): Achieving API Awesomeness

(10) APIs and API Landscapes

Design Patterns make designing APIs easier
Design Patterns make navigating landscapes easier
Design Patterns are continually evolving vocabularies
Design Patterns should reflect product needs
- Why a product should have certain properties/capabilities
- What can be done to address these issues
- How a team may choose to implement the resolution

Awesome APIs Erik Wilde (@dret): Achieving API Awesomeness

(11) API Stylebook: Error Format

API Stylebook: Error Format

Awesome APIs Erik Wilde (@dret): Achieving API Awesomeness

(12) Excellent API Management → Awesome APIs

Easy to design → Design Scope and Vocabulary
Easy to implement → Useful Components
Easy to discover → Rich Description
Easy to use → Rich Documentation
Easy to control → Connective Fabric Instrumentation
Easy to combine → Coherent Designs
Easy to change → Open Design
Easy to withdraw → Lifecycle Thinking

Interface ≠ Implementation

Outline (Interface ≠ Implementation)

Introduction [3]
Awesome APIs [6]
Interface ≠ Implementation [4]
Example: API Change Management [3]
Conclusions [2]

Interface ≠ Implementation Erik Wilde (@dret): Achieving API Awesomeness

(14) Design and Constraints

Design depends largely on constraints. [http://www.markwunsch.com/eames] (Charles Eames [https://en.wikipedia.org/wiki/Charles_and_Ray_Eames])

Why are constraints driven by business and/or client needs
What should be design patterns addressing the constraints
How should be support/tools for implementing the what

Interface ≠ Implementation Erik Wilde (@dret): Achieving API Awesomeness

(15) APIs are Interfaces

There is no "Microservice API"

Interface ≠ Implementation Erik Wilde (@dret): Achieving API Awesomeness

(16) Changing Culture

Microservices are changing the way APIs are implemented and managed
- Velocity as the main goal
- More design freedom for product teams (APIs and implementation)
- More complex runtime needs (diversity requires operational excellence)
Enterprise IT has discovered loose coupling [http://dret.net/netdret/publications#pau09a] and called it Microservices
- Individuals and interactions over processes and tools
- Working software over comprehensive documentation
- Customer collaboration over contract negotiation
- Responding to change over following a plan

Interface ≠ Implementation Erik Wilde (@dret): Achieving API Awesomeness

(17) A Microservices Landscape

By Lachlan Donald from Melbourne, Australia (Sharpest tool in the shed) [CC BY 2.0 (http://creativecommons.org/licenses/by/2.0)], via Wikimedia Commons

Example: API Change Management

Outline (Example: API Change Management)

Introduction [3]
Awesome APIs [6]
Interface ≠ Implementation [4]
Example: API Change Management [3]
Conclusions [2]

Example: API Change Management Erik Wilde (@dret): Achieving API Awesomeness

(19) API Change Management in API Strategy

API change management becomes increasingly important
- Microservices optimize for quick design/deployment/development/decommissioning
- Even in MSA-land there are Experience APIs meant to deliver some API stability
APIs can change in terms of features and will be decommissioned at some point
- Robust extensibility [http://dret.typepad.com/dretblog/2016/04/robust-extensibility.html] helps to facilitate non-breaking API changes
- Hypermedia helps as a pattern to move extensibility beyond data models
- Semantic versioning [http://semver.org/] may be used to keep track of API changes
- HTTP Sunsetting [http://dret.typepad.com/dretblog/2015/08/http-sunset-header.html] can be used to signal upcoming sunsets on the HTTP level [http://webconcepts.info/concepts/http-header/Sunset]
Always follow the why/what/how triad for API strategy
- Why: Some services/consumers are interested in how an API will change
- What: Follow principles/patterns/protocols to manage/expose API changes
- How: Support tooling/services to implement and test pattern behavior

Example: API Change Management Erik Wilde (@dret): Achieving API Awesomeness

(20) HTTP `Sunset`: An Even Simpler Example

API Documentation guidelines may ask for change management documentation
- Requirement: Can be as simple as making documentation discoverable on deploy
- Resolution: Can be as simple as stating that there is no change management
Discoverability and machine-readability are different issues
- Making description resources discoverable can be validated during deployment
- Every API entering the landscape must make change management documentation discoverable
- For some classes of APIs/services additional requirements may be put in place
One possible requirement is that Public APIs must support Sunset [http://webconcepts.info/concepts/http-header/Sunset]
- Services must document/describe the support of Sunset
- Services may implement Sunset any way they like
- The simplest option may be Sunset policies on a gateway

Example: API Change Management Erik Wilde (@dret): Achieving API Awesomeness

(21) Capability Sedimentation

Capability Sedimentation

Conclusions

Outline (Conclusions)

Introduction [3]
Awesome APIs [6]
Interface ≠ Implementation [4]
Example: API Change Management [3]
Conclusions [2]

Conclusions Erik Wilde (@dret): Achieving API Awesomeness

(23) DevOps Your APIs!

APIs increasingly turn into central business assets
Do not mix interface and implementation issues
Have a lifecycle perspective of API management

Conclusions Erik Wilde (@dret): Achieving API Awesomeness

(24) Thanks! Q&A

What's Next?

Slides online: dret.net/lectures/api-days-zurich-2017 [http://dret.net/lectures/api-days-zurich-2017]
Slide sources: dret/lectures [http://github.com/dret/lectures/tree/master/api-days-zurich-2017] on GitHub [http://github.com/]
Me: http://dret.net/netdret/ [http://dret.net/netdret/]
Twitter: @dret [http://twitter.com/dret]

September 26, 2017 API Days Zürich 2017 [http://www.apidays.io/events/zurich-2017]