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