The document discusses the development of a five-sided prism polarizing web API, emphasizing various approaches such as code-first, contract-first, and test-driven development. It highlights trade-offs associated with each method, particularly the challenges of refactoring brittle API contracts and managing cross-cutting concerns. The content also promotes a hands-on workshop aimed at teaching participants about API design, testing, and deployment.

1. A five-sided prism
polarizing Web API
development
Jerome Louvel
Chief Geek & Founder
@jlouvel

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

3. Pink Floyd
Dark side of the moon
DATA
API
PRISM

4. DRIVEN
TEST
API
prism

5. Code-first

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

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

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

9. @jlouvel 9
Brittle API contract
Refactoring might
easily break the
implicit contract

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

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

12. @jlouvel 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
An API contract diff
tool would be handy,
any taker?

13. @jlouvel 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?

14. @jlouvel 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

15. DATA-first

16. 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

17. @jlouvel 17
Pretty tabular…
Not much
control on the
API contract

18. @jlouvel 18
Dumb API
Dumb API:
no business
logic out of
the box

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

20. Contract-first

22. @jlouvel 22
Twitter poll
Not statistically
significant :-)
Interesting
feedback!

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

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

25. Facilitate
team
collaboration

26. 👨🏾
👩🏼
Backend
team
Frontend
team
Collaborate on
contract
Contract ready,
mock generated
Yay! Shorter time
to market!

27. Code generation
can overwrite
customization
Favor composition over
inheritance!

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

29. TEST-first

30. @jlouvel 30
Test Driven Development
RED
GREENREFACTOR

31. Behavior driven:
clarifies how the
API is working

32. Can ensure API
implementation
and behavior
are in sync

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

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

35. @jlouvel 35
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

36. DOC-first

37. Use case
driven, great for
onboarding

38. Doesn’t necessarily
generate a useful
contract

39. Natural
language is
ambiguous
ORANGE

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

41. @jlouvel
Summary

42. @jlouvel 42
Five-sided prism polarizing APIs development
API
prism
TEST
No good or one way of
tackling Web API
development,
just tradeoffs! Pick your side,
but do it well!

43. @jlouvel 43
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.

44. @jlouvel
Thanks for your attention

45. @jlouvel 45
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

46. @jlouvel 46
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

47. @jlouvel 47
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