You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2017/09/18 17:11:57 UTC
incubator-juneau-website git commit: Add speil about DIs.
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 <ja...@apache.org>
Authored: Mon Sep 18 13:11:48 2017 -0400
Committer: JamesBognar <ja...@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>
<!-- ======================================================================================================= -->