forked from innoq/ROCA
/
index.html
161 lines (155 loc) · 7.49 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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
---
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 —
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>
<p>ROCA splits into two parts: The <a href="#server-side">server-side</a>
and the <a href="#client-side">client-side</a> architecture.
The server-side consists of
RESTful backends, serving human-readable content as well as
services for machine-to-machine communication, either public or internal.
The client-side focuses on a sustainable and maintainable usage of
JavaScript and CSS, based on the principle of Progressive
Enhancement. This technique is pursued by nearly every basic
web technology, e.g. HTML or HTTP.
Client and server are largely independent
from, yet complement each other.
<h2 id="server-side">Server-side</h2>
<ol>
<li id="rest">The server application adheres to
REST principles, i.e. it 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 within 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="#rest">rest</a>]
</li>
<li id="application-logic">All application logic resides
on the server. [<a href="#application-logic">application-logic</a>]
</li>
<li id="http">The client interacts with the server through
RESTful HTTP requests. [<a href="#http">http</a>]
</li>
<li id="link">A user must be able to link to a specific
piece of information, e.g. by copying the address from the
browser's address bar and pasting it into an e-mail,
creating a bookmark, or using any of the fancier ways to
share URIs. [<a href="#link">link</a>]
</li>
<li id="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="#non-browser">non-browser</a>]
</li>
<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="auth">All authenticated communication relies on HTTP
Basic or Digest Authentication, typically combined
with SSL, possibly with client
certificates. Alternatively, because of the limits of
browser-native authentication (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="#auth">auth</a>]
</li>
<li id="cookies">Cookies may not be used for purposes other than
authentication or user tracking. [<a href="#cookies">cookies</a>]
</li>
<li id="session">There may not be any session state beyond
what’s needed for simple algorithmic validation of
authentication information. [<a href="#session">session</a>]
</li>
<li id="browser-controls">The browser controls like the back, forward
and refresh buttons must work as expected.
I.e. the back button should take the users where they
expect to be taken to (the last meaningful resource they
worked with).
A browser refresh should not cause a re-rendering of the login or
home page instead of the page the user was 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="#browser-controls">browser-controls</a>]
</li>
</ol>
<h2 id="client-side">Client-side</h2>
<ol>
<li id="posh">The server returns structured semantic HTML markup that is
independent of layout information and client behavior.
[<a href="#posh">posh</a>]
</li>
<li id="accessibility">It must be possible to access each page's information
and functionality by using accessibility tools like screen readers.
[<a href="#accessibility">accessibility</a>]
</li>
<li id="layout">
CSS is used for formatting and layout. This is done following the
principles of <a href="http://en.wikipedia.org/wiki/Progressive_enhancement"
title="Progressive enhancement">progressive enhancement</a>, e.g. to allow
a browser not capable of CSS3 features still to use a CSS3-based site.
</li>
<li id="unobtrusive-javascript">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="#unobtrusive-javascript">unobtrusive-javascript</a>]
</li>
<li id="no-duplication">The same functionality must not be implemented
redundantly on both the client (JavaScript) and the server.
Thus, due to the <a href="#application-logic">application logic
requirement</a>, application logic must not reside on the client-side.
[<a href="#no-duplication" class="anchor">no-duplication</a>]
</li>
<li id="know-structure"> The server code may not "know" 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="#know-structure" class="anchor">know-structure</a>]
</li>
<li id="static-assets">All JavaScript code and CSS 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 <a href="http://coffeescript.org/" title="CoffeeScript">CoffeeScript</a> or
<a href="http://www.lesscss.de/" title="LSS CSS">LESS</a>,
as the respective code is usually pre-compiled as part of the release
process.) [<a href="#static-assets" class="anchor">static-assets</a>]
</li>
<li id="historyapi">Any dynamic routing or URI state
modification triggered by JavaScript on the client
side should use the HTML5 History API.
[<a href="#historyapi">historyapi</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>.