Qype
API:
Lessons
Learned
A
retrospec3ve
on
REST-‐ful
API
design
July
2012
MaDhias
Käppler
Qype
GmbH
Slide 2
Slide 2 text
A
brief
history...
• Qype’s
API
is
deployed
as
a
RoR
2.3
app
• Online
since
end
of
2008
• Primary
purpose
was
serving
the
iOS
app
• Strictly
REST-‐ful,
small
feature
set
GET http://api.qype.com/v1/places/1
Slide 3
Slide 3 text
Architecture
DB
SOLR
API
app
Model
Mappings
Controllers
Website
app
AR
Models
Search
Logic
Search
Logic
SOLR
Ruby
bindings
Serializers
Slide 4
Slide 4 text
Today
• Load
~60M
req/month
• ~2000
registered
consumers
• 99%
of
traffic
caused
by
0.01%
of
consumers
• Consumers
vastly
differ
in
requirements
• REST
paradigm
broken
up
in
many
places
Slide 5
Slide 5 text
Today
(cont.)
• Over
the
years,
complexity
grew
with
the
requirements
– More
feature
rich
mobile
apps
– MORE
mobile
apps
– More
diverse
API
consumers
• The
result?
Slide 6
Slide 6 text
Feature
creep
Slide 7
Slide 7 text
Prolifera3on
Slide 8
Slide 8 text
What
you
end
up
with
Slide 9
Slide 9 text
So
what’s
the
point?
Slide 10
Slide 10 text
API
design
is
hard.
Slide 11
Slide 11 text
Service
APIs
vs.
Websites
• Mistakes
in
API
design
are
not
forgiven!
– Client
lock-‐in
• Clients
can
differ
vastly
– Mobile
app
vs.
Web
mash-‐up
• Authen3ca3on
and
access
control
– An
API
is
meant
to
access
your
core
data
by
design
• Performance
maDers
(even
more)
Slide 12
Slide 12 text
How
can
we
fix
all
that?
Slide 13
Slide 13 text
Mistakes
in
API
design
are
not
forgiven.
No,
but...
Slide 14
Slide 14 text
Versioning.
Slide 15
Slide 15 text
Versioning
• Granularity
– service
vs
endpoint
versioning
• Architecture/deployment
– One
app
per
version?
• E.g.
qype-‐api-‐v2
– One
engine
per
version?
• E.g.
app/engines/v2
– One
class
per
version?
• E.g.
app/controllers/resource_controller_v2.rb
Slide 16
Slide 16 text
Versioning
(cont.)
• Tes3ng?
– i.e.
to
which
version
does
a
test
apply?
• Code
sharing
vs.
code
duplica3on?
– i.e.
not
all
routes
may
change
with
an
increment
• Also
affects
caching
etc.
• Gems:
– hDps://github.com/bploetz/versionist
– hDps://github.com/filtersquad/rocket_pants
Slide 17
Slide 17 text
Clients
can
differ
vastly.
Slide 18
Slide 18 text
Build
abstrac3ons
for
things
that
change.
Slide 19
Slide 19 text
Modularity.
Slide 20
Slide 20 text
A
modular
architecture
Core
API
Apps
AAL
Partner
AAL
Standard
API
consumers
Partner
1
Partner
N
App
1
App
N
Slide 21
Slide 21 text
(Modularity.)
REST.
Slide 22
Slide 22 text
Seriously.
Slide 23
Slide 23 text
Why
REST?
• Keeps
the
interface
lean
and
mean
• Shared
understanding
of
ac3ons
• Makes
a
system
connected
• Makes
responses
cacheable
• It’s
SIMPLE!
Slide 24
Slide 24 text
But:
simple
can
be
bad!
• Our
apps
are
not
simple
• Hence,
a
simple
API
is
not
always
suitable
• REST
paradigm
can
be
sokened
on
an
AAL
– Batch
requests
– {
“requests”:
[
{
“method”:
“get”,
“uri”:
“hDp://...”
}
...
]
}
Slide 25
Slide 25 text
(Modularity.)
Resource
mapping.
Slide 26
Slide 26 text
Resource
mapping
• Qype
API
employs
custom
resource
mapper
• Goal:
– Map
AR
models
to
intermediate
format,
then
serialize
– Review.first.to_api(:hash)
• Gems:
– hDps://github.com/rails/jbuilder/
– hDps://github.com/nesquena/rabl
Slide 27
Slide 27 text
(Modularity.)
Serializa3on.
Slide 28
Slide 28 text
json
>>
xml.
Slide 29
Slide 29 text
Authen3ca3on
&
access
control.
Slide 30
Slide 30 text
OAuth?
Leave
the
complexity
to
established
Web
technology.
Slide 31
Slide 31 text
Performance.
Slide 32
Slide 32 text
Caching,
caching,
caching.
Slide 33
Slide 33 text
Don’ts
and
Do’s.
Slide 34
Slide 34 text
Don’t:
GET
hDp://yourapi.com?consumer=x
if consumer == x
...
end
Slide 35
Slide 35 text
Don’t:
GET
hDp://yourapi.com/resource?a=1
“resource”: {
“a+1”: 2
}
Slide 36
Slide 36 text
Don’t:
POST
hDp://yourapi.com/resource.json
field
missing
Slide 37
Slide 37 text
Do:
Be
consistent
with
API
status
codes.
Slide 38
Slide 38 text
Do:
Expect
bad
request
parameters.
Slide 39
Slide 39 text
Do:
Support
par3al
updates
(PATCH).
Slide 40
Slide 40 text
Do:
PREPARE
FOR
CHANGE!
Slide 41
Slide 41 text
Outlook.
Slide 42
Slide 42 text
Acceptance
tes3ng
• Crea3ng
an
acceptance
test
suite
for
a
service
API
is
not
simple
• Recommended
for
deep
end-‐2-‐end
tests
• Test
set-‐up
/
tear-‐down
• RSpec
+
consumer
subjects
Slide 43
Slide 43 text
Documenta3on
• Bad:
put
away
in
a
wiki
• Good:
close
to
the
code
• BeDer:
is
part
of
the
code
– Leverage
REST
representa3ons
– Self-‐documen3ng
API
code