A five-sided prism polarizing Web API development

Slide 1

Slide 1 text

A five-sided prism polarizing Web API development Guillaume Laforge Product Ninja & Advocate @glaforge

Slide 2

Slide 2 text

We know about APIs! http://restlet.com

Slide 3

Slide 3 text

We know about APIs! http://restlet.com

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

Pink Floyd Dark side of the moon

Slide 6

Slide 6 text

API PRISM

Slide 7

Slide 7 text

CODE API PRISM

Slide 8

Slide 8 text

DATA CODE API PRISM

Slide 9

Slide 9 text

CONTRACT DATA CODE API PRISM

Slide 10

Slide 10 text

No content

Slide 11

Slide 11 text

API prism

Slide 12

Slide 12 text

API prism CONTRACT DATA CODE

Slide 13

Slide 13 text

DOC TEST API prism CONTRACT DATA CODE

Slide 14

Slide 14 text

BEHAVIOR DRIVEN DOC TEST API prism CONTRACT DATA CODE

Slide 15

Slide 15 text

Code-first

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

Fire up IDE Setup favorite tech stack Start coding!

Slide 18

Slide 18 text

Fire up IDE Setup favorite tech stack Start coding! Easy to get started with for a developer

Slide 19

Slide 19 text

@glaforge 7 Java annotation hell…

Slide 20

Slide 20 text

@glaforge 7 Java annotation hell… Often annotation heavy in Java: Annotation driven development

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

No code, only annotations, just the method signature!

Slide 23

Slide 23 text

No code, only annotations, just the method signature! And that’s real life code!

Slide 24

Slide 24 text

@glaforge 9 Brittle API contract

Slide 25

Slide 25 text

@glaforge 9 Brittle API contract Refactoring might easily break the implicit contract

Slide 26

Slide 26 text

@glaforge 10 Spaghetti coding

Slide 27

Slide 27 text

@glaforge 10 Spaghetti coding Mixing URL paths, logging, business logic, security constraints, API related annotations…

Slide 28

Slide 28 text

@glaforge 10 Spaghetti coding Cross-cutting concerns intermixed Mixing URL paths, logging, business logic, security constraints, API related annotations…

Slide 29

Slide 29 text

No content

Slide 30

Slide 30 text

Logging, security, transactions, session management, exception handling…

Slide 31

Slide 31 text

Logging, security, transactions, session management, exception handling… One line of business logic!

Slide 32

Slide 32 text

@glaforge 12 You don’t always have the choice Inheriting existing code bases, services, Web APIs? • not a choice, you’ll work code-first! Mitigation: safe-guards • derive a contract • build step to check  contract conformance

Slide 33

Slide 33 text

Slide 34

Slide 34 text

@glaforge 13 Textual diff vs semantic diff?

Slide 35

Slide 35 text

@glaforge 13 Textual diff vs semantic diff? – Renamed path /users/{user_id} into /v1/users/{user_id} + Added path /v1/users

Slide 36

Slide 36 text

@glaforge 13 Textual diff vs semantic diff? – Renamed path /users/{user_id} into /v1/users/{user_id} + Added path /v1/users Also messages warning the changes are backward incompatible?

Slide 37

Slide 37 text

@glaforge 14 Pros and cons

Slide 38

Slide 38 text

@glaforge 14 Pros and cons Easy to get started with for a developer

Slide 39

Slide 39 text

@glaforge 14 Pros and cons Easy to get started with for a developer Refactoring might easily break the implicit contract

Slide 40

Slide 40 text

@glaforge 14 Pros and cons Easy to get started with for a developer Refactoring might easily break the implicit contract Often annotation heavy in Java: Annotation driven development

Slide 41

Slide 41 text

@glaforge 14 Pros and cons Easy to get started with for a developer Refactoring might easily break the implicit contract Cross-cutting concerns intermixed Often annotation heavy in Java: Annotation driven development

Slide 42

Slide 42 text

DATA-first

Slide 43

Slide 43 text

No content

Slide 44

Slide 44 text

Existing database: relational, NoSQL, graph Data schema: SQL schema, IDL, JSON schema… Spreadsheet: CSV, Excel, Google Sheets Existing CRUD: CRUD Web API,   3rd party Web API

Slide 45

Slide 45 text

Existing database: relational, NoSQL, graph Data schema: SQL schema, IDL, JSON schema… Spreadsheet: CSV, Excel, Google Sheets Existing CRUD: CRUD Web API,   3rd party Web API Handy to expose existing data

Slide 46

Slide 46 text

@glaforge Demo: APISpark &   Google Sheets wrapper

Slide 47

Slide 47 text

@glaforge 18 Pretty tabular…

Slide 48

Slide 48 text

@glaforge 18 Pretty tabular… Not much control on the API contract

Slide 49

Slide 49 text

@glaforge 19 Dumb API

Slide 50

Slide 50 text

@glaforge 19 Dumb API Dumb API: no business logic out of the box

Slide 51

Slide 51 text

@glaforge 20 Pros and cons

Slide 52

Slide 52 text

@glaforge 20 Pros and cons Handy to expose existing data

Slide 53

Slide 53 text

@glaforge 20 Pros and cons Handy to expose existing data Not much control on the API contract

Slide 54

Slide 54 text

@glaforge 20 Pros and cons Handy to expose existing data Not much control on the API contract Dumb API: no business logic out of the box

Slide 55

Slide 55 text

Contract-first

Slide 56

Slide 56 text

No content

Slide 57

Slide 57 text

No content

Slide 58

Slide 58 text

@glaforge 23 Twitter poll

Slide 59

Slide 59 text

@glaforge 23 Twitter poll Not statistically significant :-)

Slide 60

Slide 60 text

@glaforge 23 Twitter poll

Slide 61

Slide 61 text

@glaforge 23 Twitter poll Interesting feedback!

Slide 62

Slide 62 text

@glaforge 23 Twitter poll

Slide 63

Slide 63 text

No content

Slide 64

Slide 64 text

Contract as the source of truth

Slide 65

Slide 65 text

Contract as the source of truth Also a key communication element!

Slide 66

Slide 66 text

No content

Slide 67

Slide 67 text

Can derive & generate useful artifacts Client SDKs Server skeletons Static, dynamic, live mocks Test stubs Sandbox & live playgrounds Static documentation Documentation portal

Slide 68

Slide 68 text

No content

Slide 69

Slide 69 text

Facilitate team collaboration

Slide 70

Slide 70 text

! "

Slide 71

Slide 71 text

! " Backend team Frontend team

Slide 72

Slide 72 text

! " Backend team Frontend team

Slide 73

Slide 73 text

! " Backend team Frontend team

Slide 74

Slide 74 text

! " Backend team Frontend team Collaborate on contract Contract ready, mock generated

Slide 75

Slide 75 text

! " Backend team Frontend team Collaborate on contract Contract ready, mock generated Yay! Shorter time to market!

Slide 76

Slide 76 text

No content

Slide 77

Slide 77 text

Code generation can overwrite customization

Slide 78

Slide 78 text

Code generation can overwrite customization Favor composition over inheritance!

Slide 79

Slide 79 text

@glaforge 29 Pros and cons

Slide 80

Slide 80 text

@glaforge 29 Pros and cons Contract as the source of truth

Slide 81

Slide 81 text

@glaforge 29 Pros and cons Contract as the source of truth Facilitate team collaboration

Slide 82

Slide 82 text

@glaforge 29 Pros and cons Contract as the source of truth Facilitate team collaboration Can derive & generate useful artifacts

Slide 83

Slide 83 text

@glaforge 29 Pros and cons Contract as the source of truth Facilitate team collaboration Can derive & generate useful artifacts Code generation can overwrite customization

Slide 84

Slide 84 text

TEST-first

Slide 85

Slide 85 text

@glaforge 31 Test Driven Development RED

Slide 86

Slide 86 text

@glaforge 31 Test Driven Development RED GREEN

Slide 87

Slide 87 text

@glaforge 31 Test Driven Development RED GREEN REFACTOR

Slide 88

Slide 88 text

@glaforge 31 Test Driven Development RED GREEN REFACTOR

Slide 89

Slide 89 text

@glaforge Demo: DHC by Restlet

Slide 90

Slide 90 text

No content

Slide 91

Slide 91 text

Behavior driven: clarifies how the API is working

Slide 92

Slide 92 text

No content

Slide 93

Slide 93 text

Can ensure API implementation and behavior are in sync

Slide 94

Slide 94 text

No content

Slide 95

Slide 95 text

Harder to derive & generate useful artifacts

Slide 96

Slide 96 text

Harder to derive & generate useful artifacts Not impossible, but not available yet

Slide 97

Slide 97 text

No content

Slide 98

Slide 98 text

Hard to define tests without anything to test

Slide 99

Slide 99 text

Hard to define tests without anything to test Mitigation: Solutions with live mocks can ease authoring tests for defining the behavior

Slide 100

Slide 100 text

@glaforge 37 Pros and cons

Slide 101

Slide 101 text

@glaforge 37 Pros and cons Behavior driven: clarifies how the API is working

Slide 102

Slide 102 text

@glaforge 37 Pros and cons Behavior driven: clarifies how the API is working Harder to derive & generate useful artifacts

Slide 103

Slide 103 text

@glaforge 37 Pros and cons Behavior driven: clarifies how the API is working Harder to derive & generate useful artifacts Hard to define tests without anything to test

Slide 104

Slide 104 text

@glaforge 37 Pros and cons Behavior driven: clarifies how the API is working Harder to derive & generate useful artifacts Hard to define tests without anything to test Can ensure API implementation and behavior are in sync

Slide 105

Slide 105 text

DOC-first

Slide 106

Slide 106 text

@glaforge Demo: Silk

Slide 107

Slide 107 text

No content

Slide 108

Slide 108 text

Use case driven, great for onboarding

Slide 109

Slide 109 text

No content

Slide 110

Slide 110 text

Doesn’t necessarily generate a useful contract

Slide 111

Slide 111 text

ORANGE

Slide 112

Slide 112 text

Natural language is ambiguous ORANGE

Slide 113

Slide 113 text

@glaforge 43 Pros and cons

Slide 114

Slide 114 text

@glaforge 43 Pros and cons Use case driven, great for onboarding

Slide 115

Slide 115 text

@glaforge 43 Pros and cons Use case driven, great for onboarding Doesn’t necessarily generate a useful contract

Slide 116

Slide 116 text

@glaforge 43 Pros and cons Use case driven, great for onboarding Doesn’t necessarily generate a useful contract Natural language is ambiguous

Slide 117

Slide 117 text

@glaforge Summary

Slide 118

Slide 118 text

@glaforge 45 Five-sided prism polarizing APIs development API prism CONTRACT DATA CODE DOC TEST

Slide 119

Slide 119 text

@glaforge 45 Five-sided prism polarizing APIs development API prism CONTRACT DATA CODE DOC TEST

Slide 120

Slide 120 text

@glaforge 45 Five-sided prism polarizing APIs development API prism CONTRACT DATA CODE DOC TEST No good or one way of tackling Web API development,   just tradeoffs!

Slide 121

Slide 121 text

@glaforge 45 Five-sided prism polarizing APIs development API prism CONTRACT DATA CODE DOC TEST No good or one way of tackling Web API development,   just tradeoffs! Pick your side, but do it well!

Slide 122

Slide 122 text

@glaforge 46 Get in the flow! The developer workflow! Thursday, May 26 — 1:50pm — Birch The API ecosystem provides powerful tools, online services and definition formats for designing, testing, running, or managing APIs. All share common purposes: improve our productivity when developing an API, allow us to collaborate more effectively, or share our creations with the world! But developers have already invented efficient tactics to streamline their development, gathered experience with and sharpened their tools of trade. The result is that the services or formats mentioned before can actually also get in their way, and interrupt their development flow, as they have to resort to get out of their routine and processes, to use them. What can API tooling vendors do to reconcile the habits of developers with their tools? In this session, Guillaume Laforge, Restlet's Product Ninja & Advocate, will talk about building, versioning & dependency management of API artifacts, scenario & conformance testing, API documentation, continuous integration, multi-environment continuous deployment, and team collaboration! Let’s get back into the development flow!

Slide 123

Slide 123 text

@glaforge Thanks for your attention

Slide 124

Slide 124 text

@glaforge 48 Image credits • Pink Floyd’s Dark Side of the Moon prism  https://i.ytimg.com/vi/NJQnzmH6jgc/maxresdefault.jpg • Thumb-up  https://upload.wikimedia.org/wikipedia/commons/thumb/f/fb/Thumbs_up.svg/2000px-Thumbs_up.svg.png • Thumb-down  https://upload.wikimedia.org/wikipedia/commons/thumb/b/b8/Thumbs_down.svg/1000px- Thumbs_down.svg.png • Engine start  https://www.flickr.com/photos/npobre/2601582256 • Data graph  https://upload.wikimedia.org/wikipedia/commons/9/9b/Social_Network_Analysis_Visualization.png • Spaghetti  https://upload.wikimedia.org/wikipedia/commons/4/4a/Pollo_funghi_spaghetti_-_Paesano_Restaurant.jpg • Northern mocking birg  https://upload.wikimedia.org/wikipedia/commons/c/cf/Northern_Mocking_bird_- _Mimus_polyglottos.JPG

Slide 125

Slide 125 text

@glaforge 49 Image credits • Boarding  https://c2.staticflickr.com/4/3024/2503923533_8381d55537_b.jpg • Contract  https://pixabay.com/static/uploads/photo/2014/08/26/19/20/document-428333_960_720.jpg • Orange paint  http://www.publicdomainpictures.net/pictures/20000/velka/painting-wall-11291581001pYx.jpg • Orange fruit  https://www.flickr.com/photos/manicomi/2260527943 • Handbook  http://www.intexte.net/docenligne/carnet_autie.jpg • Behavior  http://www.thebluediamondgallery.com/pictures/behavior.jpg • Orsay Museum clock  https://www.flickr.com/photos/davidden/2320748091 • Factory workers  https://upload.wikimedia.org/wikipedia/commons/0/08/Seagate_Wuxi_China_Factory_Tour.jpg

Slide 126

Slide 126 text

@glaforge 50 Image credits • Hell  https://upload.wikimedia.org/wikipedia/commons/f/f5/ An_angel_leading_a_soul_into_hell._Oil_painting_by_a_followe_Wellcome_L0030887.jpg • Excel  https://i.ytimg.com/vi/nbYi2x84EW0/maxresdefault.jpg • Broken glass  https://upload.wikimedia.org/wikipedia/commons/thumb/6/67/Broken_glass.jpg/1280px-Broken_glass.jpg • Truth  https://pixabay.com/static/uploads/photo/2013/07/25/11/52/truth-166853_960_720.jpg • Car assembly line  https://upload.wikimedia.org/wikipedia/commons/f/f1/Hyundai_car_assembly_line.jpg • Team collaboration  https://static.pexels.com/photos/7092/desk-office-hero-workspace.jpg