(3) Learning from Legacy Landscapes

• Various teams or units have an existing (proto-)API culture
• The organizational landscape should combine and harmonize these
  • Learning across teams/units and establish good practices
  • Identify where support and tooling can make the biggest impact
• Landscapes can be analyzed according to landscape aspects
  • Aspects can be used to better understand how APIs are designed and implemented
  • Aspects can be used to observe the landscape and understand its evolution

(4) API Landscape Aspects

(5) V1: Variety

• APIs come in many different shapes (on different levels)
  • API style moved from RPC (SOAP) to Web APIs
  • Web API style starts embracing query-style APIs (GraphQL)
• Allow more than one way to address a problem
  • Embrace diversity as a way to explore new ways to solve a problem

Example Question: How easy is it for your landscape to embrace and support a new API technology?

(6) V2: Vocabulary

• APIs are languages that define how two parties communicate
• Each API is a mix of reused technology and problem-specific definitions
  • Reusing generic metamodels such as XML or JSON is a natural choice for most
  • Reusing specific models is a harder design task
• Maximizing reuse benefits producers and consumers
  • Producers don't have to re-invent the wheel for solved problems
  • Consumers can understand part of the API because they know it already

Example Question: Is there an easy way for developers to discover the vocabularies that are in use throughout existing APIs?

(7) V3: Volume

• API volume is a good thing and should be encouraged
  • More components in an ecosystem mean more choice and better selection
  • Selection should be within the ecosystem, not getting into the ecosystem
• Guidelines and support needs to grow and evolve along ecosystem growth
  • Identifying bottlenecks for the product teams helps to make teams more productive
  • Identifying bottlenecks for the ecosystem helps to eliminate participation barriers

Example Question: How easy is it for developers to design, implement, and deploy a new product?

(8) V4: Velocity

• Change frequency is a good thing and should be encouraged
• Changes in consumption ideally are invisible to producers
  • Onboarding is invisible to producers
  • Scalability should be built into each product
• Changes in products ideally are invisible to consumers
  1. Change management [V7: Versioning (1)] provides a robust product evolution path
  2. Product evolution is opaque and consumers always use their favorite version

Example Question: Does anything in the API landscape slow down teams when creating or changing APIs?

(9) V5: Vulnerability

• Every API is a possible attack vector into a capability
• Security is easy to get wrong and hard to get right
• Security often gets API programs started
• Identity can become an important asset for large organizations
  • GDPR is hard to get right without solid identity management

Example Question: Are APIs designed from the ground up to be potentially externalizable?

(10) V6: Visibility

• Product catalogs are essential for product success
• Visibility refinement depends on the expected target audience
  • Private APIs may be able to get away with just making them findable
  • Partner APIs already need some marketing so that partners will notice
  • Public APIs may need a comprehensive plan for a competitive market presence

Example Question: How easy it is for architects, teams, and consumers to explore the entire API landscape?

(11) V7: Versioning

• API success creates potential problem for API products
  • More usage means more feedback means more input and motivation to improve the product
  • More usage means greater risk for potential disruption of existing consumers
• Managing products and their implementations
  • Implementations should use well-know schemes such as Semantic Versioning [http://semver.org/]
  • APIs should expose a subset of the implementation version information
  • API management can take care of some product management issues

Example Question: Are APIs designed and implemented so that changes create as little disruption as possible?

(12) V8: Volatility

• Products in ecosystems appear, change, and disappear
  • Change is not a problem but a feature that is essential for ecosystem growth
• Treating dependencies responsibly increases product resilience
  • Not making any assumptions about APIs always being accessible
  • Always behaving well when APIs are inaccessible
• Client-side products (such as SDKs) need to be resilient
• Testing always should include degraded and inaccessible API dependencies

Example Question: Are all dependencies implemented to be visible and to behave responsibly when some APIs fail?

(14) Got Strategy?

• There is no one-size-fits-all API Strategy
• Strategy always depends on context
  • What do you want to improve/achieve with APIs?
  • What does your organization look like?
  • What is the main value that you produce?
  • What does the market look like?
  • What do your customers look like?
  • What does your competition look like?

(15) Business Pillar

• Increase delivery speed of capabilities and products
• Decrease cost of product development and adaptation
• Improve insight into products and value chains
• Aligning/unifying business and IT: Business, rewritten by software™

(16) Organizational Pillar

• Increased team autonomy increases team delivery speed
• Structures across teams build communities of practice
• API support and platform provided by Center for Enablement (C4E)
• Team practices inform and form the API guidelines

Any organization that designs a system will produce a design whose structure is a copy of the organization's communication structure. [http://www.melconway.com/Home/Conways_Law.html] (Mel Conway [https://en.wikipedia.org/wiki/Melvin_Conway])

(17) Technology Pillar

• Constrain what products have to do (not how)
• No hidden channels bypassing the API strategy
• API guidelines for protocols, patterns, and practices
• Lifecycle for technology maturity and support

(18) Two API Perspectives

• APIs as external interfaces (outside in)
  • Direct API monetization (API as a product)
  • API foundation for user journeys (omnichannel)
  • Value chain optimization (outsourced APIs)
• APIs as internal componentization (inside out)
  • Moving from integration to interconnection (IT modernization)
  • Decoupling products and their development cycles and speed
  • Improving capability reuse across the whole organization

(19) API Strategy = Pillars × Perspectives

(21) API Program

• From vision to strategy to execution
  • Vision (why): APIs are a necessary part of digital transformation
  • Strategy (what): What do we want to do with APIs and what APIs do we want?
  • Program (how): How do we establish/nurture/evolve/manage our API landscape?
• API programs are supposed to operate continuously
  • Individual products are added and modified and removed
  • The landscape of products and dependencies changes continuously
  • Continuous architecting evolves the landscape over time

(22) API Program: Assessment/Enablement/Coaching

(23) Continuous API Management

• Assessment uses analysis and observations
  • Figuring out the status quo
  • Monitoring the landscape for directing investments
  • Cultivating collaboration and feedback channels
• Enablement addresses identified gaps
  • Creating and maintaining API strategy/program/guidelines
  • Trainings and workshops for enabling all teams
• Coaching for continuous architecting
  • Monitoring the API landscape and identifying changing practices
  • Monitoring technologies and tools for improving the practice

(24) Example 1: Robust Extensibility [http://dret.typepad.com/dretblog/2016/04/robust-extensibility.html]

• Meaningful Core Semantics
  • The core of the API allows clients to have meaningful interactions
  • The core of the API is robust over time
• Well-Defined Extension Points
  • APIs should be clear about where extensions are allowed
  • API tests can make sure that the extension points are properly implemented
• Well-Defined Processing Model
  • Extensions are well-defined and their handling is well-defined as well
  • mustIgnore is a popular and good choice for extension processing
  • How to learn about extensions is a different matter

(25) Example 2: API First [https://www.apiscene.io/product/api-first-the-essence-of-digital-transformation/]

• API first establishes APIs as first-class citizens
  • API as first UI: APIs become designed artefacts
  • API before implementation: Mocking APIs before implementing them
  • API documentation: APIs replace direct communications
• APIs needs to be established as business-level concept
  • Designing/describing APIs at the functionality level
  • APIs are the design glue between business and IT
• Adjust the design process to cover API design as well
  • User stories are used as input to API stories
  • API stories can help to elicit APIs from various user stories

(27) Thanks!

• Slides online: dret.net/lectures/oreilly-sa-ca-2019 [http://dret.net/lectures/oreilly-sa-ca-2019]
• More information about myself:
  • Twitter: @dret [http://twitter.com/dret]
  • LinkedIn: linkedin.com/in/netdret [http://www.linkedin.com/in/netdret]
  • Web: dret.net/netdret/ [http://dret.net/netdret/]

(28) Rate Today's Session