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 <jamesbog...@apache.org> Authored: Mon Sep 18 13:11:48 2017 -0400 Committer: JamesBognar <jamesbog...@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> <!-- ======================================================================================================= -->
