Upload
restlet
View
209
Download
0
Embed Size (px)
Citation preview
A five-sided prism polarizing Web API
development
Jerome LouvelChief Geek & Founder
@jlouvel
Pink Floyd
Dark side of the moon
DATA
API
PRISM
DRIVEN
TEST
APIprism
Code-first
Fire up IDE
Setup favorite
tech stack
Start coding!
Easy to get
started with for
a developer
@jlouvel7
Java annotation hell…
Often annotation
heavy in Java:
Annotation driven
development
No code, only
annotations, just the
method signature!
And that’s real life code!
@jlouvel9
Brittle API contract
Refactoring might
easily break the
implicit contract
@jlouvel10
Spaghetti coding
Cross-cutting
concerns
intermixed
Mixing URL paths, logging,
business logic, security
constraints, API related
annotations…
Logging, security,
transactions, session
management,
exception handling…
One line of
business logic!
@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?
@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?
@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
DATA-first
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
@jlouvel17
Pretty tabular…
Not much
control on the
API contract
@jlouvel18
Dumb API
Dumb API:
no business
logic out of
the box
@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
Contract-first
@jlouvel22
Twitter poll
Not statistically
significant :-)
Interesting
feedback!
Contract as
the source
of truth
Also a key
communication
element!
Can derive &
generate
useful artifacts
Client SDKs Server skeletons
Static, dynamic,
live mocks
Test stubs
Sandbox & live
playgrounds
Static
documentation
Documentation
portal
Facilitate
team
collaboration
👨🏾
👩🏼Backend
team
Frontend
team
Collaborate on
contractContract ready,
mock generated
Yay! Shorter time
to market!
Code generation
can overwrite
customization
Favor composition over
inheritance!
@jlouvel28
Pros and cons
Contract as
the source of
truth
Facilitate
team
collaboration
Can derive &
generate useful
artifacts
Code generation
can overwrite
customization
TEST-first
@jlouvel30
Test Driven Development
RED
GREENREFACTOR
Behavior driven:
clarifies how the
API is working
Can ensure API
implementation
and behavior
are in sync
Harder to derive
& generate
useful artifacts
Not impossible, but
not available yet
Hard to define
tests without
anything to test
Mitigation:
Solutions with live mocks
can ease authoring tests
for defining the behavior
@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
DOC-first
Use case
driven, great for
onboarding
Doesn’t necessarily
generate a useful
contract
Natural
language is
ambiguous
ORANGE
@jlouvel40
Pros and cons
Use case
driven, great for
onboarding
Doesn’t necessarily
generate a useful
contract
Natural
language is
ambiguous
@jlouvel
Summary
@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!
@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.
@jlouvel
Thanks for your attention
@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
@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
@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