OSCON 2017 - Fake It Before You Make It: Mocking Your Way to Better HTTP APIs

Slide 1

Slide 1 text

Ian Zelikman ian.zelikman@gmail.com @izcoder Fake It Before You Make It: Mocking Your Way to Better HTTP APIs Dave Forgac dave@forgac.com @tylerdave

Slide 2

Slide 2 text

Slides, Examples, & More: BetterAPIs.com

Slide 3

Slide 3 text

Terminology

Slide 4

Slide 4 text

REST

Slide 5

Slide 5 text

REST Standard

Slide 6

Slide 6 text

REST Standard Architectural Style

Slide 7

Slide 7 text

REST Standard Architectural Style HTTP w/ Constraints

Slide 8

Slide 8 text

REST Standard Architectural Style HTTP w/ Constraints REST-inspired HTTP APIs

Slide 9

Slide 9 text

JSON

Slide 10

Slide 10 text

JSON JavaScript Object Notation

Slide 11

Slide 11 text

JSON JavaScript Object Notation { "things": [ "foo", "bar" ], "message": "Hello, World!" }

Slide 12

Slide 12 text

JSON Schema

Slide 13

Slide 13 text

JSON Schema { "title": "Example Schema", "type": "object", "properties": { "displayName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] }

Slide 14

Slide 14 text

YAML

Slide 15

Slide 15 text

YAML Serialization format

Slide 16

Slide 16 text

YAML Serialization format (More) human-readable

Slide 17

Slide 17 text

YAML Serialization format (More) human-readable Superset of JSON

Slide 18

Slide 18 text

YAML Serialization format (More) human-readable Superset of JSON Broad Support

Slide 19

Slide 19 text

YAML Example --- talk: title: Fake It Before You Make It subtitle: Mocking Your Way to Better HTTP APIs topics: - apis - development bio: > A talk about defining API contracts before developing implementations. ...

Slide 20

Slide 20 text

This Talk

Slide 21

Slide 21 text

Requirement

Slide 22

Slide 22 text

Requirement Accept POST

Slide 23

Slide 23 text

Requirement Accept POST Return OK / validation errors

Slide 24

Slide 24 text

Implementation

Slide 25

Slide 25 text

Implementation Accept POST

Slide 26

Slide 26 text

Implementation Accept POST Return OK / validation errors

Slide 27

Slide 27 text

“That's not really what we wanted.”

Slide 28

Slide 28 text

“That's not really what we wanted.”

Slide 29

Slide 29 text

We provided { "valid": false, "errors": { "field_1": "too short" "field_2": "required", } } They expected { "valid": false, "errors": [ { "field": "field_1" "error": "too short", }, { "error": "required" "field": "field_2", } ] } The Difference *simplified example

Slide 30

Slide 30 text

Can we do better?

Slide 31

Slide 31 text

Can we do better?

Slide 32

Slide 32 text

API Contract!

Slide 33

Slide 33 text

API Contract

Slide 34

Slide 34 text

API Contract Consumer ↔ Provider

Slide 35

Slide 35 text

API Contract Consumer ↔ Provider Interface Specification

Slide 36

Slide 36 text

API Contract Consumer ↔ Provider Interface Specification SLA, ToS, Limits, Pricing, etc.

Slide 37

Slide 37 text

API Specification

Slide 38

Slide 38 text

API Specification Machine Readable

Slide 39

Slide 39 text

API Specification Machine Readable Requests / Responses

Slide 40

Slide 40 text

API Specification Machine Readable Requests / Responses Basis of Contract

Slide 41

Slide 41 text

Spec Formats

Slide 42

Slide 42 text

Spec Formats WSDL

Slide 43

Slide 43 text

Spec Formats WSDL WADL

Slide 44

Slide 44 text

For REST(-like) APIs

Slide 45

Slide 45 text

OpenAPI Spec (fka Swagger)

Slide 46

Slide 46 text

OpenAPI Spec (fka Swagger) JSON or YAML

Slide 47

Slide 47 text

OpenAPI Spec (fka Swagger) JSON or YAML OpenAPI Initiative

Slide 48

Slide 48 text

Swagger / OpenAPI Spec 2.0 (1/3) swagger: '2.0' info: version: '1.0.0' title: Fake Better API description: > This is a basic example API for our talk at http://betterapis.com. termsOfService: http://betterapis.com/terms/ contact: name: API Team email: apiteam@betterapis.com url: http://betterapis.com/contact/ host: api.betterapis.com basePath: / securityDefinitions: {} schemes: - http consumes: - application/json produces:

Slide 49

Slide 49 text

Swagger / OpenAPI Spec 2.0 (2/3) paths: /foo: get: operationId: listFoo produces: - application/json parameters: - name: limit in: query required: false default: 10 type: integer format: int32 description: maximum number of foo to return responses: 200: description: List all foo schema: type: array

Slide 50

Slide 50 text

Swagger / OpenAPI Spec 2.0 (3/3) definitions: Foo: title: Foo description: An example type of object type: object properties: name: type: string score: type: integer format: int32

Slide 51

Slide 51 text

RAML

Slide 52

Slide 52 text

RAML YAML Specification

Slide 53

Slide 53 text

RAML YAML Specification Modeling

Slide 54

Slide 54 text

RAML (1/3) #%RAML 1.0 title: Fake Better API version: 1.0.0 baseUri: http://api.betterapis.com/ baseUriParamaters: {} documentation: - title: Fake Better API content: This is a basic example API for our talk at http://betterapis.com.

Slide 55

Slide 55 text

RAML (2/3) types: Foo: displayName: Foo description: An example type of object type: object properties: name: required: false displayName: name type: string score: required: false displayName: score type: integer format: int32

Slide 56

Slide 56 text

RAML (3/3) /foo: get: displayName: listFoo queryParameters: limit: required: false default: 10 displayName: limit description: maximum number of foo to return type: integer format: int32 responses: 200: description: List all foo body: application/json: displayName: response description: List all foo type: array

Slide 57

Slide 57 text

API Blueprint

Slide 58

Slide 58 text

API Blueprint Documentation as Specification

Slide 59

Slide 59 text

API Blueprint Documentation as Specification MarkDown + Extensions

Slide 60

Slide 60 text

API Blueprint (1/2) FORMAT: 1A HOST: http://api.betterapis.com/ # Fake Better API This is a basic example API for our talk at http://betterapis.com. # Foo [/foo{?limit}] ## listFoo [GET] + Parameters + limit (number, optional) - maximum number of foo to return + Default: 10 + Response 200 (application/json) List all foo

Slide 61

Slide 61 text

API Blueprint (2/2) # Data Structures ## Foo (object) An example type of object ### Properties + `name` (string, optional) + `score` (number, optional)

Slide 62

Slide 62 text

Comparison

Slide 63

Slide 63 text

Comparison User-base

Slide 64

Slide 64 text

Comparison User-base Tooling

Slide 65

Slide 65 text

Comparison User-base Tooling Language Support

Slide 66

Slide 66 text

Comparison User-base Tooling Language Support Recent Events

Slide 67

Slide 67 text

Comparison User-base Tooling Language Support Recent Events It Depends...

Slide 68

Slide 68 text

Defining Spec

Slide 69

Slide 69 text

Defining Spec Implementation First

Slide 70

Slide 70 text

Defining Spec Implementation First Contract First

Slide 71

Slide 71 text

Defining Spec Implementation First Contract First Integrated

Slide 72

Slide 72 text

Benefits

Slide 73

Slide 73 text

Documentation

Slide 74

Slide 74 text

Testing

Slide 75

Slide 75 text

Code Generation

Slide 76

Slide 76 text

Mocking

Slide 77

Slide 77 text

Almost Demo Time!

Slide 78

Slide 78 text

Almost Demo Time! Integrated Framework

Slide 79

Slide 79 text

Almost Demo Time! Integrated Framework Connexion (Python)

Slide 80

Slide 80 text

Almost Demo Time! Integrated Framework Connexion (Python) Spec as Config: Routing Validation Serialization

Slide 81

Slide 81 text

Spec Write / Update Publish Mock Fake it ➡ Make it API Implement Validate

Slide 82

Slide 82 text

Demo

Slide 83

Slide 83 text

Tooling

Slide 84

Slide 84 text

Tooling Frameworks

Slide 85

Slide 85 text

Tooling Frameworks Mocking

Slide 86

Slide 86 text

Tooling Frameworks Mocking Validation / Testing

Slide 87

Slide 87 text

Resources BetterAPIs.com Further Reading

Slide 88

Slide 88 text

Ian ian.zelikman@gmail.com @izcoder Thank You! Please leave feedback! "Rate This Session" on schedule listing Dave dave@forgac.com @tylerdave