Twelve Patterns to Create Evolvable APIs

Mike AmundsenAPI Academy / CA

@mamund

Drawings by Diogo Lucas@diogoclucas

#mcaTravels

http://apiacademy.co

?

I want to be able to...1. Change/Add Objects (payloads)2. Change/Add Addresses (URLs)3. Change/Add Actions (links and forms)

The OAA Challenge1. Change/Add Objects (payloads)2. Change/Add Addresses (URLs)3. Change/Add Actions (links and forms)

The OAA Challenge1. Change/Add Objects (payloads)2. Change/Add Addresses (URLs)3. Change/Add Actions (links and forms)

"[A] dynamic system that has extreme late binding in all

aspects." -- Alan Kay, 2003

Evolvable API Patterns

Twelve Patterns for Evolvable APIsFour Design PatternsFour Basic PrinciplesFour Shared Agreements

Design Patterns

Design Patterns1.PASS MESSAGES, NOT OBJECTS2.SHARE VOCABULARIES, NOT MODELS3.USE THE REPRESENTOR PATTERN4.PUBLISH PROFILES

Pass Messages, Not Objects"I'm sorry that coined the term 'objects' for this

topic. The big idea is 'messaging'."

Alan Kay, 1998

Pass Messages, Not ObjectsBodies SHOULD be sent using a highly-structured metadata-rich format such as:HALCollection+JSONSirenUBERAtom,etc.

Pass Messages, not ObjectsWhat problem does this solve?

I don’t need to share your object model to interact with you.

Machines can now manage their own internal models independently.

Share Vocabularies, Not Models"It is easier to standardize representation and relation types than objects and object-specific

interfaces."-- Roy Fielding

Share Vocabularies, Not ModelsAll messages SHOULD rely only on standardized identifiers (for data/action) based on shared vocabularies.

IANA Link Relation ValuesSchema.orgMicroformatsDublin CoreActivity Streams

Share Vocabularies, Not ModelsWhat problem does this solve?

Vocabulary is how we “evaluate and select”

Machines can now evaluate and select without direct human interaction.

Use the Representor Pattern"Use a special filter, a Message Translator,

between other filters or applications to translate one data format into another."

- Gregor Hohpe

Use the Representor PatternYou SHOULD implement a message translator to convert internal models into public messages.

Standard Resource Model (WeSTL)Strategy Messages Format Dispatch

Use the Representor PatternWhat problem does this solve?

Sometimes we need to translate our conversations in order to communicate.

Machines can now “negotiate” the language of a conversation.

Publish Profiles"Profiles provide a way to create a ubiquitous

language for talking about APIs (resources) for both humans and machines."

-- Mark Foster

Publish ProfilesAll messages SHOULD be accompanied by one or more PROFILE identifiers.

Define all possible data and actionsUse Profile Standard (RFC6906)Servers emit profile URIClients validate profile URI

Publish ProfilesWhat problem does this solve?

I need to know what we’re talking about.

Machines can now validate domain topics easily

Messages

Norman's Action Lifecycle

Donald Norman

Employing the RPW Loop

Design loosely-coupled interoperable services

Basic Principles

Basic Principles5. MUST IGNORE6. MUST FORWARD7. PROVIDE MRU8. USE IDEMPOTENCE

Must Ignore“The main goal of the MUST IGNORE pattern

of extensibility is to allow backwards- and forwards-compatible changes.”

- David Orchard

Must IgnoreClients MUST IGNORE any data/inputs that the client does not understand.

Must IgnoreWhat problem does this solve?

Ignoring what we don’t understand lets us “do our own thing” w/o knowing everyone’s job

Machines can now focus on their own job, not everyone’s job.

MUST FORWARD“A proxy MUST forward unrecognized header

fields…”-- RFC 7230

A proxy MUST forward an unknown header A proxy MUST forward unrecognized header fields

Must ForwardClients MUST FORWARD (unchanged) any input fields (URL or FORM) that the client does not recognize.

Must ForwardWhat problem does this solve?

We don’t edit for others around us.

Machines can now co-operate w/o full understanding of other’s work

Provide MRU (Most-Recently-Used)“A feature of convenience allowing users to

quickly see and access the last few used files and documents.”

-- Wikipedia

Provide MRUServices SHOULD return the most recently-used (MRU) LINKS and FORMS in all responses.

Provide MRUWhat problem does this solve?

We need most-used tools close at hand

Machines can now find most-used affordances easily

Use Idempotence“Can be applied multiple times without

changing the result beyond the initial application.”-- Wikpedia

Use IdempotenceAll network requests SHOULD be idempotent in order to allow clients to safely repeat them when response is unclear.

Use IdempotenceWhat problem does this solve?

If things didn’t work right the first time, we need to try again.

Machines can now safely “try again”

Networks

"Data on the Inside vs. Data on the Outside, Helland (2005) http://cidrdb.org/cidr2005/papers/P12.pdf

Programming the Network

Pat Helland

"Data on the Inside vs. Data on the Outside, Helland (2005) http://cidrdb.org/cidr2005/papers/P12.pdf

Programming the Network

Pat Helland

"Data on the Inside vs. Data on the Outside, Helland (2005) http://cidrdb.org/cidr2005/papers/P12.pdf

Programming the Network

Pat Helland

Build Network-Aware Implementations

Shared Agreements

Shared Agreements 9. USE RELATED10. USE NAVIGATION11. PARTIAL SUBMIT12. STATE WATCH

Use Related“By watching what you click on in search results, Google can learn that you favor particular sites.” – Danny Sullivan, 2009

Use RelatedServices SHOULD return a RELATED LINK that responds with ALL the possible actions for this context.

Use RelatedWhat problem does this solve?

I can’t remember everything, need an easy way to look up instructions.

Machines can now “look up” the available affordances.

Use Navigation“To achieve a single goal which can be broken

down into dependable sub-tasks.”-- Design Patterns (@uipatterns)

Use NavigationServices SHOULD provide "next/previous" LINK to handle multi-step workflow with "cancel", "restart", & "done."

Use NavigationWhat problem does this solve?

I can’t keep all the steps in my head

Machines can now navigate through a long series of steps safely.

Partial Submit“Think of the actions as approximations of what

is desired.”-- Donald Norman

Partial SubmitServices SHOULD accept partially filled-in FORM and return a new FORM with the remaining fields.

Partial SubmitWhat problem does this solve?

I sometimes only know part of the story.

Machines can now interact in small parts and not always be perfect.

State Watch“Data representing variables in a dynamical

system…”-- Jens Rassmussen

State Watch“Data representing variables in a dynamical

system…”-- Jens Rassmussen

State WatchServices SHOULD allow clients to subscribe to WATCH VALUES so that clients can determine "done."

Use State WatchWhat problem does this solve?

My boss doesn’t always set my goals.

Machines can now set their own goals and act accordingly.

Hypermedia Affordance

By Dgies - Own work, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=13691666

The words hypertext, hyperlink, and hypermedia were coined by Ted Nelson around 1965.

Ted Nelson's hyperlinks (1965)

Ted Nelson

What is Hypermedia?[Hypermedia] is not constrained to be linear. Hypertext is text which contains links to other texts.

https://www.w3.org/WhatIs.html

Affordances"The affordances of the environment are what

it offers ... what it provides or furnishes, either for good or ill.

James Gibson, 1977

James Gibson Ecological Approach to Visual Perception, Gibson, 1979

Affordances“When I say Hypertext, I mean the simultaneous

presentation of information and controls such that the information becomes the affordance

through which the user obtains choices and selects actions.”

Roy Fielding, 2008

Roy Fielding Architectural Styles and the Design of Network-based Software Architectures, Fielding, 2001

Affordances are the reason for hypermedia

Enable Connected Services

Summary

Programming the Network brings new challenges

Twelve Patterns for Evolvable APIsFour Design PatternsFour Basic PrinciplesFour Shared Agreements

Design Patterns (for interop)1.PASS MESSAGES, NOT OBJECTS2.SHARE VOCABULARIES, NOT MODELS3.THE REPRESENTOR PATTERN4.PUBLISH PROFILES

Basic Principles (for networks)5. MUST IGNORE6. MUST FORWARD7. PROVIDE MRU8. USE IDEMPOTENCE

Shared Agreements (for services) 9. USE RELATED10. USE NAVIGATION11. PARTIAL SUBMIT12. STATE WATCH

http://g.mamund.com/12-patterns

Twelve Patterns to Create Evolvable APIs

Mike AmundsenAPI Academy / CA

@mamund

Drawings by Diogo Lucas@diogoclucas