design [for error | explorable systems]
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].
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.