API World 2016 - A five-sided prism polarizing Web API development

A five-sided prism polarizing Web API

development

Jerome LouvelChief Geek & Founder

@jlouvel

We know about

APIs!

http://restlet.com

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