juneau-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jamesbog...@apache.org
Subject incubator-juneau-website git commit: Add speil about DIs.
Date Mon, 18 Sep 2017 17:11:57 GMT
Repository: incubator-juneau-website
Updated Branches:
  refs/heads/asf-site 55ec4eb00 -> 414f13aec


Add speil about DIs.

Project: http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/commit/414f13ae
Tree: http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/tree/414f13ae
Diff: http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/diff/414f13ae

Branch: refs/heads/asf-site
Commit: 414f13aec15ec53e354c78456e0c16084a5b2444
Parents: 55ec4eb
Author: JamesBognar <jamesbognar@apache.org>
Authored: Mon Sep 18 13:11:48 2017 -0400
Committer: JamesBognar <jamesbognar@apache.org>
Committed: Mon Sep 18 13:11:48 2017 -0400

----------------------------------------------------------------------
 content/about.html | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/414f13ae/content/about.html
----------------------------------------------------------------------
diff --git a/content/about.html b/content/about.html
index c59b3f9..12bdaa3 100644
--- a/content/about.html
+++ b/content/about.html
@@ -171,7 +171,7 @@
 				<td>
 					<ul style='margin:0px 10px;'>
 						<li>Java 6
-						<li>Apache HttpClient 4.5
+						<li>Apache HttpClient 4.5.3
 					</ul>
 				</td>
 			</tr>
@@ -233,7 +233,7 @@
 					<ul style='margin:0px 10px;'>
 						<li>Java 6
 						<li>Servlet 3.1
-						<li>Apache HttpClient 4.5
+						<li>Apache HttpClient 4.5.3
 					</ul>
 				</td>
 			</tr>
@@ -1755,6 +1755,48 @@
 			<ul class='doctree'>
 				<li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-rest-server'>juneau-rest-server</a>
for more information.
 			</ul>
+			
+			<h6 class='toc' id='juneau-rest-server.UIvsDI'>5.2.1 - User Interfaces (UI) vs.
Developer Interfaces (DI)</h6>
+			<div>
+				<p>
+					An important distinction needs to be made about the HTML representations produced by
the REST
+					API.  These should not be considered User Interfaces, but rather Developer Interfaces.
+				</p>
+				<p>
+					UIs should hide the end-user from the underlying architecture.
+					The audience generally consists of non-technical people not interested in how the UI
works.  
+				</p>
+				<p>
+					DIs, on the other hand, should NOT hide the end-user from the underlying architecture.
 
+					Instead, it's a thin veneer over the REST interface with the following goals:
+				</p>
+				<ul class='spaced-list'>
+					<li>Make it easy for the developer to explore and understand the REST API.
+					<li>Make it easy for the developer to debug the REST API using simple tools (hopefully
just a browser).
+				</ul>		
+				<p>
+					As a result, the following guidelines are recommended: 
+				</p>		
+				<ul class='spaced-list'>
+					<li>
+						Use titles/descriptions/asides to describe why the REST interface exists.
+						A developer knowing little about it should be able to access it with a browser and
quickly 
+						understand what it is and how to use it.
+					<li>
+						Don't hide the raw data!  
+						The HTML view should simply be considered an easier-to-read representation of the data
normally 
+						rendered in JSON or some other format.
+					<li>
+						Limit your use of Javascript!  
+						You can use it sparingly if you want to implement something simple like a pull-down
menu to 
+						simplify some task, but remember that your audience cares more about interacting with
your 
+						service programmatically using REST.  
+						The HTML is just icing on the cake.
+					<li>
+						Don't use it to implement a Web 2.0 interface!  
+						If you want a Web 2.0 UI, implement it separately ON TOP OF this REST interface.
+				</ul>		
+			</div>			
 		</div>
 
 		<!-- =======================================================================================================
-->


Mime
View raw message