api world 2016 - a five-sided prism polarizing web api development
TRANSCRIPT
![Page 1: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/1.jpg)
A five-sided prism polarizing Web API
development
Jerome LouvelChief Geek & Founder
@jlouvel
![Page 3: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/3.jpg)
Pink Floyd
Dark side of the moon
DATA
API
PRISM
![Page 4: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/4.jpg)
DRIVEN
TEST
APIprism
![Page 5: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/5.jpg)
Code-first
![Page 6: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/6.jpg)
Fire up IDE
Setup favorite
tech stack
Start coding!
Easy to get
started with for
a developer
![Page 7: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/7.jpg)
@jlouvel7
Java annotation hell…
Often annotation
heavy in Java:
Annotation driven
development
![Page 8: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/8.jpg)
No code, only
annotations, just the
method signature!
And that’s real life code!
![Page 9: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/9.jpg)
@jlouvel9
Brittle API contract
Refactoring might
easily break the
implicit contract
![Page 10: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/10.jpg)
@jlouvel10
Spaghetti coding
Cross-cutting
concerns
intermixed
Mixing URL paths, logging,
business logic, security
constraints, API related
annotations…
![Page 11: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/11.jpg)
Logging, security,
transactions, session
management,
exception handling…
One line of
business logic!
![Page 12: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/12.jpg)
@jlouvel12
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
An API contract diff
tool would be handy,
any taker?
![Page 13: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/13.jpg)
@jlouvel13
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?
![Page 14: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/14.jpg)
@jlouvel14
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
![Page 15: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/15.jpg)
DATA-first
![Page 16: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/16.jpg)
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
![Page 17: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/17.jpg)
@jlouvel17
Pretty tabular…
Not much
control on the
API contract
![Page 18: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/18.jpg)
@jlouvel18
Dumb API
Dumb API:
no business
logic out of
the box
![Page 19: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/19.jpg)
@jlouvel19
Pros and cons
Handy to
expose
existing data
Not much
control on the
API contract
Dumb API: no
business logic
out of the box
![Page 20: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/20.jpg)
Contract-first
![Page 21: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/21.jpg)
![Page 22: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/22.jpg)
@jlouvel22
Twitter poll
Not statistically
significant :-)
Interesting
feedback!
![Page 23: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/23.jpg)
Contract as
the source
of truth
Also a key
communication
element!
![Page 24: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/24.jpg)
Can derive &
generate
useful artifacts
Client SDKs Server skeletons
Static, dynamic,
live mocks
Test stubs
Sandbox & live
playgrounds
Static
documentation
Documentation
portal
![Page 25: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/25.jpg)
Facilitate
team
collaboration
![Page 26: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/26.jpg)
👨🏾
👩🏼Backend
team
Frontend
team
Collaborate on
contractContract ready,
mock generated
Yay! Shorter time
to market!
![Page 27: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/27.jpg)
Code generation
can overwrite
customization
Favor composition over
inheritance!
![Page 28: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/28.jpg)
@jlouvel28
Pros and cons
Contract as
the source of
truth
Facilitate
team
collaboration
Can derive &
generate useful
artifacts
Code generation
can overwrite
customization
![Page 29: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/29.jpg)
TEST-first
![Page 30: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/30.jpg)
@jlouvel30
Test Driven Development
RED
GREENREFACTOR
![Page 31: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/31.jpg)
Behavior driven:
clarifies how the
API is working
![Page 32: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/32.jpg)
Can ensure API
implementation
and behavior
are in sync
![Page 33: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/33.jpg)
Harder to derive
& generate
useful artifacts
Not impossible, but
not available yet
![Page 34: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/34.jpg)
Hard to define
tests without
anything to test
Mitigation:
Solutions with live mocks
can ease authoring tests
for defining the behavior
![Page 35: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/35.jpg)
@jlouvel35
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
![Page 36: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/36.jpg)
DOC-first
![Page 37: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/37.jpg)
Use case
driven, great for
onboarding
![Page 38: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/38.jpg)
Doesn’t necessarily
generate a useful
contract
![Page 39: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/39.jpg)
Natural
language is
ambiguous
ORANGE
![Page 40: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/40.jpg)
@jlouvel40
Pros and cons
Use case
driven, great for
onboarding
Doesn’t necessarily
generate a useful
contract
Natural
language is
ambiguous
![Page 41: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/41.jpg)
@jlouvel
Summary
![Page 42: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/42.jpg)
@jlouvel42
Five-sided prism polarizing APIs development
APIprism
TEST
No good or one way of
tackling Web API
development,
just tradeoffs! Pick your side,
but do it well!
![Page 43: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/43.jpg)
@jlouvel43
Master API DevOps at our Restlet meetup
Thursday, September 22nd - 7pm at our Palo Alto office
With 2 million developers on the Restlet Platform and decades of experience with API
development, Jerome will quickly catch you up with the latest in API design, testing, and
deployment.
For this hands-on workshop, you will craft your first API with the help of an API guru and the best visual API
designer on the market. You just need to come with your laptop, there’s nothing to install!
Interested? Register by clicking the link in our
pinned tweet. You will receive all the information
required prior to the meetup.
![Page 44: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/44.jpg)
@jlouvel
Thanks for your attention
![Page 45: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/45.jpg)
@jlouvel45
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
![Page 46: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/46.jpg)
@jlouvel46
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
![Page 47: API World 2016 - A five-sided prism polarizing Web API development](https://reader031.vdocuments.mx/reader031/viewer/2022030304/5879f00d1a28ab70298b480b/html5/thumbnails/47.jpg)
@jlouvel47
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