User Interfaces (UI) vs. Developer Interfaces (DI)

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.

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.

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:

- Make it easy for the developer to explore and understand the REST API.
- Make it easy for the developer to debug the REST API using simple tools (hopefully just a browser).

As a result, the following guidelines are recommended:

- 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.
- 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.
- 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 debug task, but remember that your audience cares more about interacting with your service programmatically using REST. Remember that the HTML is just icing on the cake.
- 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. The architecture is flexible enough that you could in theory pull in and use jQuery, React, Angular, or any number of sophisticated Javascript UI frameworks. Resist the urge to do so.