(3) Distributed Problem Solving

• APIs are part of distributed problem solving
• Ideal APIs can be used for a range of problems
• Problem-solving often requires combining APIs
• Language families make it easier to learn and use new APIs

(4) APIs Interactions are Conversations

• APIs support conversations between interacting peers
  • Some conversations are point-to-point (how to find the peer?)
  • Some conversations are point-to-multipoint (how are groups managed?)
  • Some conversations are point-to-ether (what does the ether do?)
• API technology does not determine the API conversation style
  • HTTP can be used for asynchronous conversations (WebHooks [http://www.webhooks.org/] pattern)
  • Synchronous conversations can be layered on top of asynchronous foundations
• Conversation goals should determine the conversation style

(5) API Style Metaphors

• Tunnel Style [Tunnel Style (1)]: Function calls in procedural programming
• URI Style [URI Style (1)]: Data access objects
• Hypermedia Style [Hypermedia Style (1)]: Browsing the Web
• Query Style [Query Style (1)]: Databases and database queries
• Event-Based Style [Event-Based Style (1)]: Event-based programming

(7) Distributed Programming

• Rooted in Remote Procedure Call (RPC) patterns
• Functions are the main abstraction and invoked at known endpoints
• Resource identifiers typically are context-dependent
• Suffers from the typical RPC problems at bigger scale
  • Failure is hard to deal with (function calls always succeed)
  • Scoped identifiers mean naming problems and no network effect
• Convenient for developers looking to code like a local program

(9) Identifiers for Resources

• Makes a major step towards a more webby service design
  • Resources are identified by URIs and thus globally unique
  • Data context may be established by using URI identifiers for resources
  • Navigational context is missing because of a lack of links
• One necessary step in the evolution of designing decentralized systems
  • Web of Data is a good starting point
  • Web of Services is what makes the Web what it is
• Developers are tempted/required to hardcode control flows
  • No navigational guidance provided by the API
  • Guidance must be hand-crafted or clients are forced to do trial-and-error

(11) Webby APIs

• Based on mixing data and controls in representations
  • Data represents the current resource state
  • Controls represent the advertised next options for clients
• Controls allow clients to work across individual APIs
  • APIs expose sets of resources and provide links
  • Clients follow links without being aware of API boundaries
• Developers must code differently from usual programming flows
  • Applications are driven by the responses that client code receives
  • Imperative programming is not the best fit for this kind of flow

(13) Querying Structured Data

• The API provides access to a rich interconnected data structure
  • Clients know the data model and understand how to query it
  • Clients want a small subset of the available data
• Querying into structure data needs an agreement on data and querying
  • Query-style APIs define a metamodel that all data models must use
  • Query-style APIs define a query language for querying data
• Loose coupling depends on if and how clients adjust to schema changes
  • Is it possible for clients to find out about schema changes?
  • Do clients have to worry about schema changes?

(15) Fire and Forget

• Synchronous communications result in tighter coupling between peers
• Asynchronous communications can make data provision easier
  • Data is tagged and submitted into some messaging fabric
  • The fabric takes care of notifying and delivering data to consumers
• The fabric is beyond the smart endpoints and dumb pipes idea
  • Smart pipes are not bad by itself but often have problems scaling
• Managing the fabric becomes an essential part of making code work
  • Who is producing data?
  • Who is consuming data?
  • What are the ways in which data can or must be tagged?
  • How is the namespace of data tagging managed?

(16) Event Sourcing: Durable Event Logs

• Application state is determined by events that have happened
  • Application state can be re-created by replaying the sequence of events
  • Persisting events becomes essential for representing application state
• Useful pattern for designs where auditing/accounting is a key component
  • Application state is determined as a function of the audit trail
  • Auditing/Accounting by definition is in sync with application state
  • Temporal reasoning becomes easier
• Isolation from external events (input/output) becomes essential
  • Event replay may be needed to recreate application state
  • Event replay must be prevented from replaying external effects

(18) Separating Read and Write Models

• Read and write can follow very different approaches
  • Reading may result in data enriched with related data or links
  • Writing may be less strict and may use fewer data items
• CQRS is a result of looking at read/write as two different services
  • Can be useful when read and write are typically different applications
  • Can be confusing when it becomes to simply read/modify/update data
• CQRS usually means having different models (not just variations)
  • Different models means that mapping can be non-trivial
  • Lightweight CQRS can be achieved with profiles [Representations for APIs; Profiles (1)] (model variations)

(20) API Styles are Tools

(21) API Style Properties

• API styles influence important API properties
  • Scalability: Number of APIs, API teams, API consumers, and API interactions
  • Usability: Problem domain, established styles, available tooling
  • Changeability: BFF, known/unknown group of consumers
  • Performance: What are critical issues in known scenarios
  • Reliability: Operational concerns and centralization/decentralization

(22) Context Considerations

• Backend for Frontend (BFF) implies tight coupling producer/consumer
  • API style and API design can be coordinated with the consumer
• Private APIs implies a smaller group of potential consumers
  • Style and design can be guided by internal guidelines/practices
• Partner APIs implies a well-known group of consumers
  • Broader appeal to consumers necessary
• Public APIs is the most loosely couple group of consumers
  • No control over consumers and their preferences/tools and development cycles

(23) API Styles in the Wild

• Tunnel Style [Tunnel Style (1)]: XML-RPC, SOAP, gRPC
• URI Style [URI Style (1)]: Swagger/OpenAPI
• Hypermedia Style [Hypermedia Style (1)]: HAL, Siren, Atom
• Query Style [Query Style (1)]: GraphQL, OData, SPARQL
• Event-Based Style [Event-Based Style (1)]: MQ, WebSub, MQTT, XMPP, AMQP

(25) There is no Style Hammer

• API styles can be combined
• Style coherence makes a API landscape more usable
• Style fundamentalism may pick the wrong tool for a problem
• Be aware of styles and pick the one that works best

(26) Thanks! Q&A

• Slides online: dret.net/lectures/politecnico-2018 [http://dret.net/lectures/politecnico-2018]
• Slide sources: dret/lectures [http://github.com/dret/lectures/tree/master/politecnico-2018] on GitHub [http://github.com/]
• Me: http://dret.net/netdret/ [http://dret.net/netdret/]
• Twitter: @dret [http://twitter.com/dret]