The document discusses REST (Representational State Transfer) architectural styles and best practices for designing web services. It covers topics like RESTful principles of using URIs and HTTP methods to manipulate resources, statelessness, hypermedia as the engine of application state, and JSON and XML media types for representing resources. It also discusses REST maturity levels, security, versioning, and error handling in RESTful web services.

1. THE GLORY OF REST

2. THEORY

3. Source: www.redorbit.com

4. WEB SERVICE
A web service is an abstraction layer, like an
operating system API or a programming
language library.

5. RPC-STYLE ARCHITECTURES
envelope full of data
HTTP and SOAP are envelope formats
RPC-Style service defines it's own vocabulary
RESTful WS share standard HTTP methods vocabulary
REST Uniform Interface

6. RESTful - different URIs for different values
RPC-style - URI (service endpoint) for something that can be
processed as a command

7. REST-RPC HYBRID ARCHITECTURES
Web service between the RESTful web
services and the purely RPC-style services

8. FEW REST-RPC EXAMPLES
The
The "REST"
Many other allegedly RESTful web services
Most web applications
del.icio.us API
Flickr web API

9. SOAP AS A COMPETITOR TO REST
The primary competitors to RESTful
architectures are RPC architectures, not
specific technologies like SOAP.

10. RICHARDSON MATURITY MODEL
Source: http://martinfowler.com

11. LEVEL 0 - THE SWAMP OF POX
HTTP POST for all interactions

12. LEVEL 1 - RESOURCES
Distinct URL per object

13. LEVEL 2 - HTTP VERBS
Rather than doing RPC style methods, we
leverage HTTP

14. LEVEL 3 - HYPERMEDIA CONTROLS
Self-describing API

15. SO WHAT IS THIS REST
THING?
REST simply dictates that a given resource have a unique
address.
You can interact with that address with standard HTTP verbs.

16. STATE AND
STATELESSNESS

17. TWO TYPES OF STATE:
1. application state - live on the client
2. resource state - live on the server

18. Resource state stays on the server and is only sent to the
client in the form of representations.
Application state stays on the client until it can be used to
create, modify, or delete a resource. Then it's sent to the
server as part of POST, PUT, or DELETE request, and
becomes resource state.
RESTful service is "stateless" if the server never stores any
application state.

19. This is where the name "Representational State Transfer"
comes from.

20. ETAGS
ETags are used to compare entities from the
same resource. By supplying an entity tag
value in a conditional request header.

21. RESOURCE-ORIENTED
BASICS
different audience
everything (interesting) thing represent as a resource
representation of resources
verbs, auxiliaries, complexity

22. THE GENERIC ROA PROCEDURE
1. Figure out the data set
2. Split the data set into resources
For each kind of resource:
3. Name the resources with URIs
4. Expose a subset of the uniform interface
5. Design the representation(s) accepted from the client
6. Design the representation(s) served to the client
7. Integrate this resource into existing resources, using hypermedia links
and forms
8. Consider the typical course of events: what’s supposed to happen?
Standard control flows like the Atom Publishing Protocol can help.
9. Consider error conditions: what might go wrong? Again, standard control
flows can help.

24. ADDRESSABILITY
REPRESENTATIONS SHOULD BE ADDRESSABLE

25. CONNECTEDNESS

27. UNIFORM INTERFACE

28. GET, PUT, AND DELETE

29. POST

30. HEAD AND OPTIONS
Retrieve a metadata-only representation: HTTP HEAD
Check which HTTP methods a particular resource
supports: HTTP OPTIONS

31. PUT VERSUS POST

32. OVERLOADING POST
The real information may be in the URI, the
HTTP headers, or the entity-body. However it
happens, an element of the RPC style has
crept into the service.

33. SAFETY AND
IDEMPOTENCE
When correctly used, GET and HEAD
requests are safe. GET, HEAD, PUT and
DELETE requests are idempotent.

34. URI DESING
URIs are supposed to designate resources, not
operations on the resources.

35. MethodMethod URI TemplateURI Template Equivalent RPCEquivalent RPC
OperationOperation
PUT users/{username} createUserAccount
GET users/{username} getUserAccount
PUT users/{username} updateUserAccount
DELETE users/{username} deleteUserAccount
GET users/{username}/profile getUserProfile
POST users/{username}/bookmarks createBookmark
PUT users/{username}/bookmarks/{id} updateBookmark
DELETE users/{username}/bookmarks/{id} deleteBookmark
GET users/{username}/bookmarks/{id} getBookmark
GET users/{username}/bookmarks?tag=
{tag}
getUserBookmarks
GET {username}?tag={tag} getUserPublicBookmarks
GET ?tag={tag} getPublicBookmarks

36. Use commas when the order of the items matters, as it
does in latitude and longitude: /earth/37.0,-95.2
Use semicolons when the order doesn’t matter: /color-
blends/red;blue
When designing URIs, use path variables to separate
elements of a hierarchy, or a path through a directed graph.
Use query variables only to suggest arguments being
plugged into an algorithm, or when the other two
techniques fail.

37. REPRESENTATIONS
Representations should be human-readable,
but computer-oriented

38. SERVICE VERSIONING
Even a well-connected service might need to
be versioned

39. SECURITY
HMAC
"Authorization: AWS " + AWSAccessKeyId+ ":" +
base64(hmac-sha1(VERB + "n" +
CONTENT-MD5 + "n" +
CONTENT-TYPE + "n" +
DATE + "n" +
CanonicalizedAmzHeaders + "n" +
CanonicalizedResource))
Authorization: AWS 44CF9590006BF252F707:jZNOcbfWmD/A/f3hSvVzXZjM2HU=

40. JSON OR XML

41. JSON

42. If all you want to pass around are atomic
values or lists or hashes of atomic values,
JSON has many of the advantages of XML: it’s
straightforwardly usable over the Internet,
supports a wide variety of applications, it’s
easy to write programs to process JSON, it
has few optional features, it’s human-legible
and reasonably clear, its design is formal and
concise, JSON documents are easy to create,
and it uses Unicode.

43. If you’re writing JavaScript in a web browser,
JSON is a natural fit. The XML APIs in the
browser are comparitively clumsy and the
natural mapping from JavaScript objects to
JSON eliminates the serialization issues that
arise if you’re careless with XML.

44. One line of argument for JSON over XML is
simplicity. If you mean it’s simpler to have a
single data interchange format instead of two,
that’s incontrovertibly the case. If you mean
JSON is intrinsically simpler than XML, well,
I’m not sure that’s so obvious. For bundles of
atomic values, it’s a little simpler. And the
JavaScript APIs are definitely simpler. But I’ve
seen attempts to represent mixed content in
JSON and simple they aren’t.

45. XML

46. XML deals remarkably well with the full
richness of unstructured data. I’m not worried
about the future of XML at all even if its death
is gleefully celebrated by a cadre of web API
designers.

47. I look forward to seeing what the JSON folks
do when they are asked to develop richer
APIs. When they want to exchange less well
strucured data, will they shoehorn it into
JSON? I see occasional mentions of a schema
language for JSON, will other languages
follow?

48. I predict there will come a day when someone
wants to federate JSON data across several
application domains. I wonder, when they
discover that the key "width" means different
things to different constituencies, will they
invent namespaces too?

49. JSON AND HYPERMEDIA
HAL Media Types
HAL and Links
HAL and Resources
HAL Embedded Resources

50. ERROR HANDLING
WHY STATUS CODES AREN’T ENOUGH?

51. A status code simply isn’t enough information most of the
time. Yes, you want to define standard status codes so that
your clients can perform reasonable branching, but you also
need a way to communicate details to the end-user, so that
they can log the information for themselves, display
information to their own end-users, and/or report it back to
you so you can do something to resolve the situation.

52. SOURCESRESTful Web Services
Microsoft REST Spec
Amazon's HMAC-SHA
HTTP Method Definitions
JSON and REST presentation
HAL Specification

53. THE END
Sławomir Chrobak /
Link to presentation:
@schrobak
http://schrobak.github.io/slides/tgor