REST
API
REST
is
not
a
standard,
but
an
architecture
@lobster1234
Slide 8
Slide 8 text
REST
API
REST
is
not
a
standard,
but
an
architecture,
which
uses
HTTP
as
a
model
for
all
interac.ons.
If
HTTP
is
a
standard,
REST
is
a
conven&on.
@lobster1234
Slide 9
Slide 9 text
@lobster1234
Slide 10
Slide 10 text
REST
API
Noun
è
Resource,
or
the
En&ty
Verb
è
Ac&on
+
Iden.fier
@lobster1234
Use
the
appropriate
HTTP
Method
to
represent
your
ac&on
@lobster1234
Slide 47
Slide 47 text
Using
POST
for
all
writes
@lobster1234
Slide 48
Slide 48 text
GET
to
retrieve,
or
search
POST
to
create,
or
upsert
PUT
to
update
(or
be)er
yet,
PATCH)
DELETE
to
delete
@lobster1234
Slide 49
Slide 49 text
Using
HTTP
PUT
or
POST
to
set
a
value
to
null
@lobster1234
Slide 50
Slide 50 text
Updates
vs.
Deletes
Everything
works
when
there
is
data,
but
what
when
there
is
no
data..?
@lobster1234
Slide 51
Slide 51 text
Use
HTTP
DELETE
to
set
a
value
to
null
Remember,
we
have
a
path
to
not
just
the
resource,
but
also
it’s
a)ributes
@lobster1234
Slide 52
Slide 52 text
DELETE
/pets//collartag
@lobster1234
Slide 53
Slide 53 text
Response
An&pa)erns
@lobster1234
Slide 54
Slide 54 text
Always
returning
HTTP
200
@lobster1234
Slide 55
Slide 55 text
@lobster1234
Slide 56
Slide 56 text
HTTP
200
OK
{
“success”
:
false
}
@lobster1234
Slide 57
Slide 57 text
HTTP
200
OK
{
“error”
:
”Person
jdoe
not
found”
}
@lobster1234
Slide 58
Slide 58 text
2xx
for
success
3xx
for
redirects/caching
4xx
for
request/client
errors
5xx
for
server
errors
@lobster1234
Slide 59
Slide 59 text
Some
Useful
(and
not
so
common)
Codes
Return
aGer
a
delete
-‐
204
Failed
database
constraint
-‐
409
Method
not
supported
-‐
405
Trying
to
ask
for
too
much
data
-‐
413
Valida&on
Failure
-‐
418
@lobster1234
Slide 60
Slide 60 text
Always
returning
a
401
for
auth
failures
Slide 61
Slide 61 text
@lobster1234
Slide 62
Slide 62 text
Auth
Use
HTTP
401
Unauthorized
to
indicate
that
the
client
needs
to
authen&cate
@lobster1234
Slide 63
Slide 63 text
Auth
Use
HTTP
403
Forbidden
to
indicate
that
the
client’s
creden&als
do
not
allow
access
to
the
requested
resource
@lobster1234
Slide 64
Slide 64 text
401
vs
403
401
=
Come
back
with
a
key
403
=
Your
key
does
not
work
for
this
lock.
@lobster1234
Slide 65
Slide 65 text
Processing
requests
synchronously,
even
&me
intensive
ones
@lobster1234
Slide 66
Slide 66 text
Async
the
opera&on,
and
return
HTTP
202
–
Accepted
@lobster1234
Slide 67
Slide 67 text
@lobster1234
Slide 68
Slide 68 text
Async
opera&on’s
response
should
help
the
caller.
{“statusUrl”:
}
@lobster1234
Slide 69
Slide 69 text
Organiza&onal
An&pa)erns
@lobster1234
Slide 70
Slide 70 text
Not
differen&a&ng
between
en..es
and
instances
@lobster1234
Slide 71
Slide 71 text
/pets?type=dog&name=big
vs
/pets/dogs/name/big
@lobster1234
Slide 72
Slide 72 text
Namespace
your
resources
in
a
collec&on
Use
paths
and
iden&fiers
to
traverse
@lobster1234
Slide 73
Slide 73 text
Using
id
in
the
resource
iden&fica&on
path
@lobster1234
Slide 74
Slide 74 text
/pets/id/1234
vs
/pets/1234
@lobster1234
Slide 75
Slide 75 text
Use
all
other
a)ributes
in
the
path,
except
the
id.
id
is
implied
@lobster1234
Slide 76
Slide 76 text
@lobster1234
Resources
in
an
island
Slide 77
Slide 77 text
@lobster1234
Slide 78
Slide 78 text
Every
en&ty
or
a
resource
is
&ed
to
others.
@lobster1234
Slide 79
Slide 79 text
Every
en&ty
or
a
resource
is
&ed
to
others.
And
you’re
stuck
guessing
the
connec&ons!
@lobster1234
Slide 80
Slide 80 text
@lobster1234
We’ll
just
return
the
IDs!
Slide 81
Slide 81 text
HATEOAS
(or
something
similar)
@lobster1234
Slide 82
Slide 82 text
Read
code
to
figure
out
the
resources
and
a)ributes.
@lobster1234
Slide 83
Slide 83 text
@lobster1234
Slide 84
Slide 84 text
Use
Meta
pages
for
resource
descrip&on
/resource/meta
/collec&on/meta
@lobster1234
Slide 85
Slide 85 text
APIs
are
not
discoverable
@lobster1234
Slide 86
Slide 86 text
Consider
a
documenta&on
generator
like
Swagger,
IODocs
@lobster1234
Slide 87
Slide 87 text
Relying
on
cookies
for
authen&ca&on
@lobster1234
Slide 88
Slide 88 text
@lobster1234
Slide 89
Slide 89 text
Accept
cookies
as
a
fallback,
but
prefer
a
query
parameter
or
HTTP
request
header.
@lobster1234
Slide 90
Slide 90 text
Storing
state
on
the
server
nodes
@lobster1234
Slide 91
Slide 91 text
Stateless
==
Simple
@lobster1234
Slide 92
Slide 92 text
Requests
either
modify
the
state
of
a
resource,
or
read
it.
All
requests
to
the
cluster
see
the
same
state
of
the
resource
@lobster1234
Slide 93
Slide 93 text
Avoid
state
as
much
as
possible.
Maintain
the
state
in
the
database.
If
you
need
to
store
transient
state
on
the
server,
it’s
a
code
(or
architecture)
smell.
@lobster1234
Slide 94
Slide 94 text
Versioning
Using
301s
to
redirect/re&re
APIs
Caching
Using
HTTP
headers
correctly
Caching
response
bodies
@lobster1234