The web frontend is effectively an API browser. Given our APIs are all served over HTTP, our browser is not really conceptually different to a general web browser. As such, it makes sense to mimic this model very closely so users will have an inherent understanding of how it's meant to behave.

In addition to this, the browser chrome should be very minimal and unobtrusive. The actual web browser's chrome will be able to provide basic navigational functionality (i.e., forward and back buttons), so the design should focus on productivity-enhancing interfaces:

• Bookmarks While API bookmarks can be made in the host browser, it may be beneficial to provide limited functionality for this in the frontend.

• Breadcrumbs As the service APIs will be mapped to meaningful URLs by the frontend's router, arguably the host browser's address bar serves this purpose. Again, however, it may be useful to provide this widget directly in the frontend.

• Administration Presumably users will want to configure the frontend to their own needs (e.g., specific bookmarks that they find useful) as well as managing their account details, insofar as that is relevant/useful.

[Wireframe here...]

More important than the browser chrome is the way in which data returned by an API is presented to the user. Ideally, we should strive for consistency -- which is possible if API data uses a supported hypermedia format -- but with the ability to fallback to native rendering when all else fails (i.e., API returning (X)HTML). If an API has the mechanism to provide layout hinting, that should also be respected.

To this end, we need to understand the kinds of data and operations that can be performed against them that can be requisitioned by an API.

The operations presented for user interaction are straightforward, as they are just the HTTP request methods:

• GET Render a hyperlink to the resource.

• POST and PUT Render the appropriate input forms that can pass the desired data to the resource. Note that it may be useful to highlight the semantic difference between these methods (i.e., idempotency) with visual styles.

• DELETE Render a button -- with an "Are you sure?" prompt -- that removes the resource.

Note that, to avoid race conditions, methods that affect data must only do so if said data is constant during the user's interaction. This can be done by validating resource checksums (e.g., ETags) before and at the event. Ideally this should be delegated to the API by referencing the original checksum upon the HTTP request. This delegation must be handled by the frontend.

As for kinds of data, these again follow the model imposed by the nature of URL addressing: specifically, collections and items. (Moreover, HTTP errors must also be accounted for.) Complexity is borne from how specific types are to be represented.

• Layout Hinting If a resource provides details on how it should be laid out (e.g., using a template, etc.), then that should be respected.

• Type Annotation If a resource provides higher-fidelity type information than what can be provided by its media type, then that should be respected. A repository of supported types and their representations should be available to the frontend.

• Duck Typing Otherwise, the frontend should use type information provided natively by the resource's media type and/or duck typing (e.g., by building a simple grammar into the aforementioned type repository) for nondescript string data.

This somewhat forces all APIs to follow this rigid model. However, as mentioned above, we allow an (X)HTML fallback for APIs that want to display data arbitrarily. This is useful for reporting-style APIs that only present information, with no functionality to mutate state.

While it might seem worthwhile to explicitly strip any state mutating functionality from (X)HTML-only resources, this may prove too limiting and be prone to false positives. Instead a clear but unobtrusive warning notice should be presented to users to this effect (e.g., "This resource should not be changed, even if the service allows it").