Uniform Interface - Speaker Deck

Slide 1

Slide 1 text

GOOD API THE QUEST FOR THE UNIFORM INTERFACE Zdenek Nemec GOOD API @zdne

Slide 2

Slide 2 text

GOOD API Zdenek Nemec API Consulting http://goodapi.co GOOD API @zdne zdne1

Slide 3

Slide 3 text

GOOD API GOOD API CONSULTING adidas API Guidelines https://adidas-group.gitbooks.io/api-guidelines

Slide 4

Slide 4 text

GOOD API UNIFORM INTERFACE What is Uniform Interface?

Slide 5

Slide 5 text

GOOD API ENGINEERING PRINCIPLE OF GENERALITY

Slide 6

Slide 6 text

GOOD API THE UNIFORM INTERFACE REFERS TO A STANDARD WAY TO DO SOMETHING REGARDLESS OF WHAT THE SPECIFIC ACTIVITY IS

Slide 7

Slide 7 text

GOOD API UNIFORM INTERFACE 1957 2017

Slide 8

Slide 8 text

GOOD API UNIFORM INTERFACE

Slide 9

Slide 9 text

GOOD API TERM COINED BY ROY T. FIELDING IN 2000

Slide 10

Slide 10 text

GOOD API SOFTWARE ENGINEERING PRINCIPLE OF GENERALITY APPLIED TO INTERFACE COMPONENT OF A COMPONENT IN DISTRIBUTED SYSTEM

Slide 11

Slide 11 text

GOOD API A CONSISTENT, PREDICTABLE WAY TO QUERY DATA AND EXERCISE ACTIONS REGARDLESS OF THE APPLICATION DOMAIN

Slide 12

Slide 12 text

GOOD API MANIFESTS AS ARCHITECTURAL STYLE CONSTRAINT TO ACHIEVE SOME DISTRIBUTED SYSTEM PROPERTIES

Slide 13

Slide 13 text

GOOD API WHY WE WANT UI System properties when we apply the UI constraint(s)

Slide 14

Slide 14 text

GOOD API THE BENEFITS OF UI

Slide 15

Slide 15 text

GOOD API SIMPLIFIED ARCHITECTURE

Slide 16

Slide 16 text

GOOD API IMPROVED VISIBILITY OF INTERACTIONS

Slide 17

Slide 17 text

GOOD API DECOUPLED COMPONENTS Enable parts to evolve independently Abstraction Layer Comp-A Comp-B no welding of components

Slide 18

Slide 18 text

GOOD API IMPROVED INTEROPERABILITY Reduces the cost of integration Two different drivers can drive any car

Slide 19

Slide 19 text

GOOD API REUSABLE CLIENT COMPONENTS Reduces development costs and time to market

Slide 20

Slide 20 text

GOOD API NO CLIENT REUSE New API 㱺 New client, albeit the API is within the same domain Smart Pallet Vendor A Smart Pallet Vendor B

Slide 21

Slide 21 text

GOOD API ENABLES AUTONOMOUS SERVICE DISCOVERY

Slide 22

Slide 22 text

GOOD API AUTONOMOUS SERVICE DISCOVERY “Get me a service that knows weather in Paris.” “Get me a service that can fulﬁll the parcel logistics of 6 pallets from Prague to Paris.” “Get me a service that can play every movies by the director of movie Avatar.”

Slide 23

Slide 23 text

GOOD API ENABLES FOR GENERAL AI

Slide 24

Slide 24 text

GOOD API UNIVERSE OF CAPABILITIES http://viv.ai

Slide 25

Slide 25 text

GOOD API THIS IS WHAT AMAZON ALEXA SKILLS, GOOGLE HOME SKILLS & VIV ARE DOING BUILD A DATABASE OF KNOWLEDGE AND SERVICES WITH UNIFORM INTERFACE…

Slide 26

Slide 26 text

GOOD API THE TRADEOFF OF UI

Slide 27

Slide 27 text

GOOD API DEGRADED EFFICIENCY UI Transformation Comp-A Comp-B Transformation

Slide 28

Slide 28 text

GOOD API UNLESS YOU ARE REALLY COUNTING BITS, WATTS OR MILLISECONDS THE UI’S BENEFITS OUTWEIGHS THE TRADEOFF

Slide 29

Slide 29 text

GOOD API THE QUEST SO FAR

Slide 30

Slide 30 text

GOOD API HOW TO ACHIEVE CONSISTENT INTERFACE • SOAP (Tunneling architectural style) • REST (Hypermedia architectural style) • Query Languages (Tunneling architectural styles) • Proprietary function libraries (RPC architectural style) • Domain-speciﬁc standards (on top of a respective style)

Slide 31

Slide 31 text

GOOD API SOAP

Slide 32

Slide 32 text

GOOD API SOAP • Uniform Interface is not part of SOAP • Added on the application level of service qualities • Security: WS-Security/SecureConversation/Trust • Transactions: WS-AtomicTransaction and WS-BusinessActivity

Slide 33

Slide 33 text

GOOD API REST

Slide 34

Slide 34 text

GOOD API REST ARCHITECTURAL STYLE

Slide 35

Slide 35 text

GOOD API REST UI CONSTRAINTS • Identiﬁcation of Resources • Manipulation Through Representations • Self Descriptive Messages • HATEOAS

Slide 36

Slide 36 text

GOOD API

Slide 37

Slide 37 text

GOOD API HATEOAS 1. All application state is kept on the client side. Changes to application state are the client’s responsibility 2. The client can only change its application state by making an HTTP request and processing the response. 3. How does the client know which requests it can make next? By looking at the hypermedia controls in the representations it’s received so far. 4. Therefore, hypermedia controls are the driving force behind changes in application state. Credit: RESTful Web APIs by Richardson & Amundsen

Slide 38

Slide 38 text

GOOD API RESTFUL WEB APIS RESTful Web APIs by Leonard Richardson & Mike Amundsen

Slide 39

Slide 39 text

GOOD API REST ARCHITECTURAL STYLE • Great in theory • In reality very few follows the UI constraints, making the interfaces incompatible • Workarounds possible via explicit standards & governance e.g. Oracle+Apiary API Style Guide

Slide 40

Slide 40 text

GOOD API FUNCTION LIBRARIES

Slide 41

Slide 41 text

GOOD API FUNCTION LIBRARIES StdLib Algorithmia FaaS with Uniform Function Interface

Slide 42

Slide 42 text

GOOD API FUNCTION LIBRARIES FaaS with Uniform Function Interface

Slide 43

Slide 43 text

GOOD API QUERY LANGUAGES

Slide 44

Slide 44 text

GOOD API SQL IS THE UNIFORM INTERFACE TO RETRIEVE AND MANIPULATE DATA REGARDLESS OF WHAT THE DATA ARE

Slide 45

Slide 45 text

GOOD API QUERY LANGUAGES GraphQL Graql SPARQL Query language as the uniform interface

Slide 46

Slide 46 text

GOOD API GraphQL

Slide 47

Slide 47 text

GOOD API BENEFITS

Slide 48

Slide 48 text

GOOD API A CONSISTENT WAY TO QUERY DATA AND EXERCISE AFFORDANCES (MUTATIONS)

Slide 49

Slide 49 text

GOOD API FOUNDATION FOR REUSABLE CLIENT Relay, Apollo, Loki

Slide 50

Slide 50 text

GOOD API DATA IDENTIFIERS ARE MORE HYPERMEDIA THAN URI* “URIs” of GraphQL are opaque: ID or “path” + ID (Relay route) * true for HTTP/LCODC$SS APIs

Slide 51

Slide 51 text

GOOD API SCHEMA (DESIGN) FIRST

Slide 52

Slide 52 text

GOOD API DATA & AFFORDANCES INTROSPECTION AT RUNTIME

Slide 53

Slide 53 text

GOOD API NO VERSIONING “GraphQL takes a strong opinion on avoiding versioning by providing the tools for the continuous evolution of a GraphQL schema.” http://graphql.org/learn/best-practices/

Slide 54

Slide 54 text

GOOD API MYTH: OVERFETCHING If you are worried about over-fetching you are probably using wrong protocol. GraphQL

Slide 55

Slide 55 text

GOOD API TRADEOFFS

Slide 56

Slide 56 text

GOOD API ONLY JSON REPRESENTATION

Slide 57

Slide 57 text

GOOD API MISSING SOME OF THE REST SYSTEM QUALITIES COD & $ which translates to the loss of extensibility and cache-ability

Slide 58

Slide 58 text

GOOD API NO AUTH STANDARD

Slide 59

Slide 59 text

GOOD API TIED TO UI DATA STRUCTURE

Slide 60

Slide 60 text

GOOD API NO STANDARD FOR DATA SEMANTICS

Slide 61

Slide 61 text

GOOD API HOWEVER THESE ARE USUALLY NON-ISSUE WIHTIN CLOSED (ENTERPRISE) NETWORK

Slide 62

Slide 62 text

GOOD API GraphQL GraphQL out of the box provides Uniform Interface and thus results in systems with: 1. Simpliﬁed Architecture 2. Increased Components Visibility 3. Decoupled Components

Slide 63

Slide 63 text

GOOD API GOOD API In fact, GraphQL is so good at providing UI, I wanted to take it and create the easiest way for everybody to get to the uniform interface…

Slide 64

Slide 64 text

GOOD API GOOD API http://deira.ai

Slide 65

Slide 65 text

GOOD API GOOD API Serverless API to provide Uniform Interface on top of existing data, functions and services http://deira.ai

Slide 66

Slide 66 text

GOOD API GOOD API http://deira.ai