design [for error | explorable systems]

2011-11-26 @ 14:40#

valuable guidance when designing a Hypermedia API (emphasis and brackets "[]" mine):

Think of each action by the user [of your API] as an attempt to step in the right direction; an error is simply an action that is incompletely or improperly specified. Think of the action as part of a natural, constructive dialog between the user [and/or user-agent] and the system [your API]. Try to support, not fight, the user's responses. Allow the user [and/or user-agent] to recover from errors, to know what was done and what happened, and to reverse any unwanted outcome. make it easy to reverse operations; make it hard to do irreversible actions. Design explorable systems [APIs].

Donald A. Norman in The Design of Everyday Things, 1990.

designing (and implementing) Hypermedia APIs is more than simply exposing server-side operations to clients (users, user-agents, etc.). instead, good Hypermedia APIs include the proper amount of affordances and constraints which allow users|user-agents to successfully interact with servers in order to complete one or more tasks in an effort to accomplish a pre-determined goal.

usability (in all its commonly-known forms and interpretations) is an essential aspect of Hypermedia. usability is, in the end, an essential aspect of all systems; esp. 'complex' ones.

how usable is your API?

Hypermedia