Resilient API Design - Speaker Deck

Slide 1

Slide 1 text

Resilient API Design

Slide 2

Slide 2 text

Resilient API Design

Slide 3

Slide 3 text

What makes a great web API?

Slide 4

Slide 4 text

What makes a great web API? • Decoupled from implementation details • Able to evolve without breaking existing clients

Slide 5

Slide 5 text

Agenda • How to introduce changes to APIs • Hypermedia • Client side hypermedia • Server side hypermedia

Slide 6

Slide 6 text

Example: Pagination

Slide 7

Slide 7 text

GET /posts

Slide 8

Slide 8 text

GET /posts{?page}

Slide 9

Slide 9 text

GET /posts?page=2

Slide 10

Slide 10 text

No content

Slide 11

Slide 11 text

No content

Slide 12

Slide 12 text

! How can we solve?

Slide 13

Slide 13 text

GET /posts{?before}

Slide 14

Slide 14 text

GET /posts?before=44

Slide 15

Slide 15 text

API Timeline

Slide 16

Slide 16 text

How do we introduce changes to our API?

Slide 17

Slide 17 text

Versioning APIs

Slide 18

Slide 18 text

/v1/posts{?page} /v2/posts{?before}

Slide 19

Slide 19 text

/posts{?page} /posts{?before}

Slide 20

Slide 20 text

API is coupled to implementation details

Slide 21

Slide 21 text

API is coupled to implementation details

Slide 22

Slide 22 text

What happens when you version an API?

Slide 23

Slide 23 text

What happens when you version an API?

Slide 24

Slide 24 text

API Client Timeline

Slide 25

Slide 25 text

How can we design the API without exposing implementation details?

Slide 26

Slide 26 text

REST Representational State Transfer

Slide 27

Slide 27 text

Anticipating change is one of the central themes of REST

Slide 28

Slide 28 text

Evolvability

Slide 29

Slide 29 text

Tight Coupling

Slide 30

Slide 30 text

"You can’t have evolvability if clients have their controls baked into their design at deployment"

Slide 31

Slide 31 text

"Controls have to be learned on the fly. That’s what hypermedia enables"

Slide 32

Slide 32 text

Hypermedia

Slide 33

Slide 33 text

Web Linking RFC 5988

Slide 34

Slide 34 text

GET /posts Link: ; rel="next", ; rel="last"

Slide 35

Slide 35 text

GET /posts?before=120 Link: ; rel="prev", ; rel="first"

Slide 36

Slide 36 text

Hypermedia API Timeline

Slide 37

Slide 37 text

WebLinking: Checking for next link if let link = response.findLink(relation: "next") { print("We have a next link with the URI: \(link.uri).") }

Slide 38

Slide 38 text

WebLinking: Introspecting Available Links for link in response.links { print("Relation: \(link.relationType)") print("URI: \(link.uri)") }

Slide 39

Slide 39 text

application/hal+json

Slide 40

Slide 40 text

Blog Post { "title": "My First Blog Post", "body": "Lorem Ipsum" }

Slide 41

Slide 41 text

Blog Post (Next Link) { "title": "My First Blog Post", "body": "Lorem Ipsum", "_links": [ { "href": "/posts/2", "relation": "next" } ] }

Slide 42

Slide 42 text

Blog Post (Self) { "title": "My First Blog Post", "body": "Lorem Ipsum", "_links": [ { "href": "/posts/1", "relation": "self" }, { "href": "/posts/2", "relation": "next" } ] }

Slide 43

Slide 43 text

Blog Post (Comments) { "title": "My First Blog Post", "body": "Lorem Ipsum", "_links": [ { "href": "/posts/1", "relation": "self" }, { "href": "/posts/2", "relation": "next" }, { "href": "/posts/1/comments", "relation": "comments" }, ] }

Slide 44

Slide 44 text

Blog Post (Embedded Comments) { "_embed": { "comments": [ { "author": "Kyle", "body": "That's a really interesting post!" "_links": [ { "href": "/posts/1/comments/1", "relation": "self" } ] } ] } }

Slide 45

Slide 45 text

Blog Post (Embedded Comments) { "_embed": { "comments": [ { "author": "Kyle", "body": "That's a really interesting post!" "_links": [ { "href": "/posts/1/comments/1", "relation": "self" } ] } ] } }

Slide 46

Slide 46 text

application/ vnd.siren+json

Slide 47

Slide 47 text

Delete Post { "properties": { "title": "My First Blog Post", "body": "Lorem Ipsum", }, "actions": [ { "name": "delete", "method": "DELETE", "href": "/posts/1" } ] }

Slide 48

Slide 48 text

Delete Post { "properties": { "title": "My First Blog Post", "body": "Lorem Ipsum", }, "actions": [ { "name": "delete", "method": "DELETE", "href": "/posts/1" } ] }

Slide 49

Slide 49 text

Create Comment { "properties": { "title": "My First Blog Post", "body": "Lorem Ipsum", }, "actions": [ { "name": "comment", "method": "POST", "href": "/posts/1/comments", "fields": [ { "name": "author", "type": "string" }, { "name": "message", "type": "string" } ] } ] }

Slide 50

Slide 50 text

Create Comment (Logged in) { "properties": { "title": "My First Blog Post", "body": "Lorem Ipsum", }, "actions": [ { "name": "comment", "method": "POST", "href": "/posts/1/comments", "fields": [ { "name": "message", "type": "string" } ] } ] }

Slide 51

Slide 51 text

Hypermedia • Remove implementation details from interface • Keep business logic on back-end, not front-end

Slide 52

Slide 52 text

It's not about exposing your database via an API

Slide 53

Slide 53 text

Semantics

Slide 54

Slide 54 text

Posts • create (maybe) • list (maybe) • first • prev • self • next • last

Slide 55

Slide 55 text

Posts • create (maybe) • list (maybe) • first • prev • self • next • last

Slide 56

Slide 56 text

Post • delete (maybe) • report (maybe) • comments (maybe) • create (maybe)

Slide 57

Slide 57 text

Comment • author • delete • report

Slide 58

Slide 58 text

Comment • author • delete • report

Slide 59

Slide 59 text

Root Posts Post Comment posts posts create delete report delete report self self ﬁrst prev next last comment self

Slide 60

Slide 60 text

Hypermedia Client

Slide 61

Slide 61 text

Hyperdrive

Slide 62

Slide 62 text

client.enter("https://example.com/")

Slide 63

Slide 63 text

client.enter("https://example.com/") // follow the 'posts' transition .flatMap(followTransition("posts"))

Slide 64

Slide 64 text

client.enter("https://example.com/") // follow the 'posts' transition .flatMap(followTransition("posts")) // we can select the first post .map { $0.representors["posts"].first }

Slide 65

Slide 65 text

client.enter("https://example.com/") // follow the 'posts' transition .flatMap(followTransition("posts")) // we can select the first post .map { $0.representors["posts"].first } // follow the 'delete' transition .flatMap(followTransition("delete"))

Slide 66

Slide 66 text

Slide 67

Slide 67 text

Slide 68

Slide 68 text

client.enter("https://example.com/") // follow the 'posts' transition .flatMap(followTransition("posts")) // Follow the 'create' transition .flatMap { client.request($0.transitions["create"], attributes: [ "title": "Hello World", "body": "My First Post", ]) }

Slide 69

Slide 69 text

Validation

Slide 70

Slide 70 text

Post • title (required) • max length: 32 • body (required) • min length: 64 • max length: 5000

Slide 71

Slide 71 text

No content

Slide 72

Slide 72 text

No content

Slide 73

Slide 73 text

JSON Schema { "type": "object", "properties": { "title": { "type": "string" "maxLength": 32 } }, "required": ["title"] }

Slide 74

Slide 74 text

JSON Schema { "type": "object", "properties": { "title": { "type": "string" "maxLength": 32 } }, "required": ["title"] }

Slide 75

Slide 75 text

Starship

Slide 76

Slide 76 text

No content

Slide 77

Slide 77 text

Server Side

Slide 78

Slide 78 text

class HelloPostResource(Resource): uri_template = '/posts/1' def get_attributes(self): return { 'title': 'Hello World', 'body': 'Hi' }

Slide 79

Slide 79 text

class SecondPostResource(Resource): uri_template = '/posts/2' def get_attributes(self): return { 'title': 'Hello Other World', 'body': 'Hello' }

Slide 80

Slide 80 text

class PostListResource(Resource): uri_template = '/posts' def get_relations(self): return { 'posts': [ HelloPostResource(), SecondPostResource() ] } router.add_root_resource('posts', PostListResource)

Slide 81

Slide 81 text

$ curl http://localhost:8080/ -H 'Accept: application/json' {"url": "/", "posts_url": "/posts"} $ curl http://localhost:8080/posts -H 'Accept: application/json' { "url": "/posts", "posts": [ { "body": "Hi", "url": "/posts/1", "title": "Hello World" }, { "body": "Hello", "url": "/posts/2", "title": "Hello Other World" } ] }

Slide 82

Slide 82 text

class PostListResource(Resource): uri_template = '/posts' def get_relations(self): ... def can_embed(self, relation): return False

Slide 83

Slide 83 text

$ curl http://localhost:8080/posts -H 'Accept: application/json' { "url": "/posts", "posts": [ { "url": "/posts/1" }, { "url": "/posts/2" } ] }

Slide 84

Slide 84 text

Hypermedia

Slide 85

Slide 85 text

Hypermedia • REST APIs must be hypertext driven • Roy Fielding on Versioning • Solving FizzBuzz with Hypermedia

Slide 86

Slide 86 text

Resources • The Hypermedia Project • Hyperdrive • Starship - Generic iOS Hypermedia Browser • HAL Specification • Siren Specification • https://github.com/kylef/WebLinking.swift • https://github.com/kylef/JSONSchema.swift

Slide 87

Slide 87 text

fuller.li/talks