API Design Lessons From Kubernetes

Slide 1

Slide 1 text

Slide 2

Slide 2 text

https://manifold.co James Bowes Technical Lead

Slide 3

Slide 3 text

@jrbowes Photo by Maximilian Weisbecker on Unsplash KUBERNETES?

Slide 4

Slide 4 text

@jrbowes

Slide 5

Slide 5 text

@jrbowes

Slide 6

Slide 6 text

@jrbowes

Slide 7

Slide 7 text

@jrbowes

Slide 8

Slide 8 text

@jrbowes Photo by Gamze Bozkaya on Unsplash THE CLIENT API

Slide 9

Slide 9 text

@jrbowes

Slide 10

Slide 10 text

@jrbowes

Slide 11

Slide 11 text

@jrbowes

Slide 12

Slide 12 text

@jrbowes Photo by Jakob Owens on Unsplash PATCHING

Slide 13

Slide 13 text

JSON Merge Patch ● Plain JSON document only containing changes ● Declarative and simple ● RFC 7386

Slide 14

Slide 14 text

JSON Merge Patch ... metadata: labels: service: worker app: marketplace spec: containers: - image: manifold/worker:1.31.18 name: worker

Slide 15

Slide 15 text

JSON Merge Patch metadata: labels: service: billing-worker spec: containers: - image: manifold/sidecar:1.0.0 name: metrics

Slide 16

Slide 16 text

JSON Merge Patch ... metadata: labels: service: billing-worker app: marketplace spec: containers: - image: manifold/sidecar:1.0.0 name: metrics

Slide 17

Slide 17 text

JSON Merge Patch ... metadata: labels: service: billing-worker app: marketplace spec: containers: - image: manifold/sidecar:1.0.0 name: metrics

Slide 18

Slide 18 text

JSON Merge Patch ● Objects are always merged ● Arrays are always replaced ● No explicit null See also JSON Patch (RFC 6902) - Operation based

Slide 19

Slide 19 text

Strategic Merge Patch ● Adds replace, merge, delete for objects and arrays ● Merge keys for array elements ● Schema defined defaults ● Client directive overrides

Slide 20

Slide 20 text

Strategic Merge Patch ... metadata: labels: service: worker app: marketplace spec: containers: - image: manifold/worker:1.31.18 name: worker

Slide 21

Slide 21 text

Strategic Merge Patch spec: containers: - image: manifold/sidecar:1.0.0 name: metrics

Slide 22

Slide 22 text

Strategic Merge Patch ... spec: containers: - image: manifold/worker:1.31.18 name: worker - image: manifold/sidecar:1.0.0 name: metrics

Slide 23

Slide 23 text

Strategic Merge Patch ... spec: containers: - image: manifold/worker:1.31.18 name: worker - image: manifold/sidecar:1.0.0 name: metrics

Slide 24

Slide 24 text

Strategic Merge Patch spec: containers: - image: manifold/sidecar:1.0.0 name: metrics - $patch: replace

Slide 25

Slide 25 text

LONG RUNNING OPERATIONS Photo by Luke Stackpoole on Unsplash @jrbowes

Slide 26

Slide 26 text

Queue Endpoint PUT https://my.api/songs/2 HTTP/1.1 202 Accepted Location: /queue/2890 status: "pending" lastMessage: "request accepted" created: "2018-09-24T13:35:05Z"

Slide 27

Slide 27 text

Queue Endpoint ● Good for infrequent operations ● Requires clients to understand two resource types ● What about resources that are continually experiencing long running changes?

Slide 28

Slide 28 text

Spec and Status ● Include operation status in the resource ● spec describes a resource’s desired state ● status describes a resource’s current state ● status does not mirror spec

Slide 29

Slide 29 text

Spec and Status apiVersion: extensions/v1beta1 kind: Deployment spec: replicas: 2 ... status: availableReplicas: 2 ...

Slide 30

Slide 30 text

@jrbowes Photo by Gamze Bozkaya on Unsplash THE INTERNAL MODEL

Slide 31

Slide 31 text

@jrbowes

Slide 32

Slide 32 text

@jrbowes

Slide 33

Slide 33 text

@jrbowes

Slide 34

Slide 34 text

@jrbowes

Slide 35

Slide 35 text

@jrbowes Photo by David Kovalenko on Unsplash LOST DATA

Slide 36

Slide 36 text

@jrbowes

Slide 37

Slide 37 text

@jrbowes

Slide 38

Slide 38 text

@jrbowes

Slide 39

Slide 39 text

@jrbowes

Slide 40

Slide 40 text

@jrbowes Photo by Fabrizio Verrecchia on Unsplash SLOW REACTIONS

Slide 41

Slide 41 text

@jrbowes

Slide 42

Slide 42 text

@jrbowes

Slide 43

Slide 43 text

@jrbowes Photo by Matt Artz on Unsplash PREVENTION AND REPAIR

Slide 44

Slide 44 text

Lost Intermediate Data ● Edge triggered ○ Track last seen revision number ○ Perform a resync on missing version ● Not an issue for level triggered

Slide 45

Slide 45 text

Stale Data ● Heartbeat ● Periodic resync (done in Kubernetes)

Slide 46

Slide 46 text

Slow Reactions ● Edge triggered ○ Keep state for last value ○ Compute change to apply with real value, last seen, and changed ● Not an issue for level triggered

Slide 47

Slide 47 text

@jrbowes Photo by Hans-Peter Gauster on Unsplash PIECING IT TOGETHER

Slide 48

Slide 48 text

TCP implementations should follow a general principle of robustness: be conservative in what you do, be liberal in what you accept from others. - Jon Postel, RFC 761

Slide 49

Slide 49 text

be exhaustive in what you send, be explicit in what you receive from others.

Slide 50

Slide 50 text

@jrbowes Photo by Annie Spratt on Unsplash WRAPPING UP

Slide 51

Slide 51 text

@jrbowes Photo by Michael Hoyt on Unsplash COLOCATE COMPLEX LOGIC WITH STATE

Slide 52

Slide 52 text

@jrbowes Photo by Roman Koester on Unsplash IDENTIFY THE AUDIENCE AND BUILD FOR THEM

Slide 53

Slide 53 text

@jrbowes Photo by Andrés Canchón on Unsplash MAKE IT HARD FOR THE AUDIENCE TO FAIL

Slide 54

Slide 54 text

Thank you!