forked from innoq/ROCA
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
144 lines (136 loc) · 6.33 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
---
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. However, we find that very often
frameworks are driven more by their authors’ personal
taste, the intent to create something new, a desire to hide the
Web and turn it into something different, or any combination of
these factors.
</p>
<p>ROCA is an attempt to define a set of recommendations -
independent of any particular framework, programming language,
or tooling - 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><a name='must-rest'></a>The server application adheres to REST principles,
i.e. the server exposes a set of resources with their own URIs
that are meaningful to a user sitting in front of a browser, all
of the information necessary for handling a request is contained
in the request itself and the resource state is maintained by the
server (stateless
communication). [<a href='#must-rest'>must-rest</a>]
</li>
<li><a name='must-server'></a>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><a name='must-non-browser'></a>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><a name='must-html'></a>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><a name='must-jslimits'></a>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>
</ol>
<h2>Suggested Practices</h2>
<p>The following concepts are encouraged, but not mandatory:</p>
<ol>
<li><a name='should-formats'></a>Resources have additional representations in other formats, e.g.
JSON and/or XML. [<a href='#should-formats'>should-formats</a>]
</li>
<li><a name='should-auth'></a>All authenticated communication relies on HTTP Basic
Authentication over SSL (or Client
Certificates). Alternatively, cookies can be used if
they include all of the state needed for the server to
process them. [<a href='#should-auth'>should-auth</a>]
</li>
<li>
<a name='should-historyapi'></a>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><a name='mustnot-cookies'></a>Cookies
are used for purposes other than
authentication. [<a href='#mustnot-cookies'>mustnot-cookies</a>]
</li>
<li><a name='mustnot-session'></a>There
is session state beyond
what’s needed for simple
algorithmic validation of
authentication
information. [<a href='#mustnot-session'>mustnot-session</a>]
</li>
<li><a name='mustnot-break-back'></a>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><a name='mustnot-break-link'></a>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><a name='mustnot-break-refresh'></a>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><a name='mustnot-jsengine'></a>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><a name='shouldnot-jsrouting'></a>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><a name='mustnot-break-accessibility'></a>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" style="border-width:0" 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>.