(3) Scaling the API Practice (Focus)

(4) Scaling the API Practice (Continuity)

(6) Increasing Product Team Productivity

• API product teams need guidance, autonomy, and support
  • Guidance helps understanding and navigating the current landscape
  • Autonomy allows choices to be made driven by product and user needs
  • Support increases productivity of teams for cross-cutting concerns
• Balancing product value and product portfolio value
  • Products focus on achieving local maxima for product value
  • Landscapes focus on achieving global maxima across all products

(7) Guidelines: Why? What? How? Test!

• Guidance needs to be motivated, clear, actionable, and testable
  • Why explains why a problem is a problem
  • What explains a design to address the problem
  • How explains how to implement the solution
  • Test provides feedback to verify compliance
• Guidance is further qualified by when it is applicable
  • Guidance evolution has stages such as experimental/production/deprecated
  • Guidance applicability is decided by API maturity stage
• Governance is about how the guidelines are enforced/encouraged

(8) CAM Landscape Compass

(9) 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?

(10) 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?

(11) 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?

(12) 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?

(13) 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?

(14) 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?

(15) 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?

(16) 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?

(17) Good Plumbing Matters

(19) Interface Design

(20) Interface Continuity and Evolution

(21) API your APIs

• Expose design-time and runtime API information in the API
  • Design-time allows automation of API landscape overview
  • Runtime allows automation of API landscape status
• Follow robust extensibility principles [http://dret.typepad.com/dretblog/2016/04/robust-extensibility.html] for these API APIs
  • Meaningful Core: Start with a simple but useful scenario
  • Extension Points: Think about how scenarios might evolve
  • Processing Model: Be clear about how extensions are handled

(22) Emerging API Patterns

• Self-description for APIs is increasing
• Problem details [http://webconcepts.info/specs/IETF/RFC/7807] as a way how APIs expose error information
  • Enables generic error handling but also allows additional information
• Home documents [http://webconcepts.info/specs/IETF/I-D/nottingham-json-home] as a way how APIs provide starting pages
  • Enables harvesting of API start points but also allows additional information
• Healthcheck reports [http://webconcepts.info/specs/IETF/I-D/inadarei-api-health-check] as a way how APIs expose status information
  • Enables landscape-level status reports but also allows additional information
• API Labels [http://dret.net/lectures/apistrat-2018] as a way for representing API product labels
  • Share API labels as a way to describe cross-cutting aspects of APIs

(24) Ecosystems win over Systems

• Ecosystems have built-in mechanisms for determining fitness
  • Systems are easy to build but hard to improve over time
  • Ecosystems are hard to build but easy to improve over time
• APIs are the plumbing that make product ecosystems work
  • Good plumbing allows the ecosystem to change and evolve organically
  • Bad plumbing means that not all potential product value is realized

(25) Thanks!

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