Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
178 lines (169 sloc) 7.29 KB
---
layout: default
title: "ROCA: Resource-oriented Client Architecture"
---
<h2>Introduction</h2>
<p>A Web application's architecture is heavily influenced by the
design decisions, both implicit and explicit, that have been
made by framework developers. Sometimes these decisions are
consciously accepted as being in line with the intended overall
system architecture. More often, though, they are accepted
simply because developers assume they embody the state of the
art of development practices.
</p>
<p>ROCA is an attempt to define a set of recommendations &mdash;
independent of any particular framework, programming language,
or tooling &mdash; that embodies the principles of what we consider to
be good web application architecture. Its purpose is to serve as
a reference, one that can be implemented as-is or be compared to
other approaches to highlight diverging design
decisions.
</p>
<h2>Mandatory Requirements</h2>
<p>A web application's architecture is compliant to the ROCA
style if it meets all of the following mandatory requirements:
</p>
<ol>
<li id="must-rest">The server application adheres to
REST principles, i.e. the server exposes a set of
resources that are meaningful to a user sitting in
front of a browser, each resource has its own URI, all
of the information necessary for handling a request is
contained in the request itself, HTTP methods are used
in line with their definition, and the resource state
is maintained by the server (stateless
communication). [<a href="#must-rest">must-rest</a>]
</li>
<li id="must-server">All application logic resides
on the server; the client interacts with the server through
RESTful HTTP requests. [<a href="#must-server">must-server</a>]
</li>
<li id="must-no-duplication">The same functionality must not be implemented
redundantly on both the client and the server.
Thus, due to the requirement above, application logic must not reside
on the client-side.
[<a href="#must-no-duplication" class="anchor">must-no-duplication</a>]
</li>
<li id="must-non-browser">It must be possible to use
the server's logic through user agents other than a browser,
e.g. a command line client such as curl or
wget. [<a href="#must-non-browser">must-non-browser</a>]
</li>
<li id="must-html">The server returns structured HTML markup that is
independent of layout information; CSS is used for
formatting. [<a href="#must-html">must-html</a>]
</li>
<li id="must-jslimits">In line with the principles
of <a href="http://en.wikipedia.org/wiki/Progressive_enhancement"
title="Progressive enhancement">progressive enhancement</a>, JavaScript is
used <a href="http://en.wikipedia.org/wiki/Unobtrusive_JavaScript"
title="Unobtrusive JavaScript">unobtrusively</a>
and the application remains usable (albeit with a
decrease in usability and convenience) if JavaScript is
disabled. [<a href="#must-jslimits">must-jslimits</a>]
</li>
<li id="must-static">All JavaScript code must be static,
and must not be dynamically generated by the server in
a form specific to the resource requested.
(Note that this does not prohibit the use of preprocessors
like CoffeeScript, as the respective code is usually pre-compiled
as part of the release process.)
[<a href="#must-static" class="anchor">must-static</a>]
</li>
</ol>
<h2>Suggested Practices</h2>
<p>The following concepts are encouraged, but not mandatory:</p>
<ol>
<li id="should-formats">Resources have additional representations in other formats, e.g.
JSON and/or XML. [<a href="#should-formats">should-formats</a>]
</li>
<li id="should-auth">All authenticated communication relies
on HTTP Basic Authentication over SSL (or Client
Certificates). Alternatively, because of browser limits in
handling basic auth (e.g. no logout, no styling), form-based
authentication in conjunction with cookies can be used. If cookies
are used, they should include all of the state needed for the
server to process them, and another authentication mechanism
should be supported for non-browser
access. [<a href="#should-auth">should-auth</a>]
</li>
<li id="should-historyapi">Any dynamic routing or URI state
modification triggered by JavaScript on the client
side should use the HTML5 History
API. [<a href="#should-historyapi">should-historyapi</a>]
</li>
</ol>
<h2>Violations</h2>
<p>The following characteristics are clear indications that the ROCA style is violated:</p>
<ol>
<li id="mustnot-cookies">Cookies
are used for purposes other than
authentication or user tracking. [<a href="#mustnot-cookies">mustnot-cookies</a>]
</li>
<li id="mustnot-session">There
is session state beyond
what&#8217;s needed for simple
algorithmic validation of
authentication
information. [<a href="#mustnot-session">mustnot-session</a>]
</li>
<li id="mustnot-break-back">The back and forward buttons don't
work as expected, i.e. they
don't take the user where they
expect to be taken to (the
last meaningful resource they
worked with). [<a href="#mustnot-break-back">mustnot-break-back</a>]
</li>
<li id="mustnot-break-link">A user can't link to a specific
piece of information, e.g. by
copying the address from the
browser's address bar and
pasting it into an email, by
creating a bookmark, or using
any of the fancier ways to
share URIs. [<a href="#mustnot-break-link">mustnot-break-link</a>]
</li>
<li id="mustnot-break-refresh">A browser refresh causes
unexpected behavior, e.g. a
re-rendering of the login or
home page instead of the page
the user is looking at, or a
(to the user) unexpected
question about wanting to
submit the same data again
(when the user doesn't recall
submitting any data,
indicating a mis-use of the
POST verb). [<a href="#mustnot-break-refresh">mustnot-break-refresh</a>]
</li>
<li id="mustnot-jsengine">The content sent to the client
mainly consists of JavaScript that retrieves the real
content from the server, requiring JavaScript to be
enabled to make any sense of the
application. [<a href="#mustnot-jsengine">mustnot-jsengine</a>]
</li>
<li id="mustnot-know-structure"> The server code "knows" the
HTML structures the client code generates (beyond CSS) or
vice versa.
Exceptions are some well defined HTML structures the server
generates to initialize the client functionality above.
[<a href="#mustnot-know-structure" class="anchor">mustnot-know-structure</a>]
</li>
<li id="shouldnot-jsrouting">Routing is done wholly on the
client side: JavaScript is used to generate and
maintain URIs used all over the application, at worst
involving hacks like hash-bang URI components.
[<a href="#mustnot-jsrouting">mustnot-jsrouting</a>]
</li>
<li id="mustnot-break-accessibility">Tools for accessibility,
e.g. screen readers, can't be
used. [<a href="#mustnot-break-accessibility">mustnot-break-accessibility</a>]
</li>
</ol>
<hr />
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License"
src="http://i.creativecommons.org/l/by-sa/3.0/88x31.png" /></a><br />
<span xmlns:dct="http://purl.org/dc/terms/"
href="http://purl.org/dc/dcmitype/Text" property="dct:title"
rel="dct:type">ROCA</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
Jump to Line
Something went wrong with that request. Please try again.