Communicating disabled/unavailable actions to clients

[erewhon]

Consider an API for a discussion forum where you have hypermedia controls for commenting (e.g. a "comment" link).  There will be a few reasons for disabling comments (either for the entire discussion or on individual posts) -- how would this be communicated properly to the user?  The server can omit the hypermedia control for specific posts, for example, but then the client can't tell the user why commenting isn't allowed -- is there a convention for communicating this?  An additional field in the response with a message or code?

[Ryan Hiebert]

On Mar 20, 2015, at 11:50 AM, erewhon <keith....@gmail.com> wrote:
>
> Consider an API for a discussion forum where you have hypermedia controls for commenting (e.g. a "comment" link). There will be a few reasons for disabling comments (either for the entire discussion or on individual posts) -- how would this be communicated properly to the user? The server can omit the hypermedia control for specific posts, for example, but then the client can't tell the user why commenting isn't allowed -- is there a convention for communicating this? An additional field in the response with a message or code?

I can’t think of a reasonable pre-existing convention that matches this. The way I’d think to expose this is some kind of a property on the post or the thread, depending on what context is appropriate for the reason that applies.

[Andrew Braae]

I'm guessing this hypothetical API is h2m, and quite close to the surface, i.e. the user interface, since a) you talk about the user and b) if it was an m2m API, and the client was a machine, then it probably couldn't care less about what was unavailable (or why).

And it sounds like you want the UI that sits over your API to display *all choices*, but grey out the ones that are not currently available? i.e. like a good old Windows menu?

And furthermore you want to allow the user to be able to easily suss out why their desired menu item is unavailable - perhaps via a tooltip or similar?

(There's a stackoverflow article here http://ux.stackexchange.com/questions/12756/dont-hide-or-disable-menu-items/12759#12759 that touches on the UI aspects of this quite well - I found it interesting how there are no concrete examples of how this is done well even from just the UI perspective).

It sounds that what you want is almost an anti-pattern for HATEOAS, where all future actions the client may take (not "might ever take") are discovered within resource representations returned from the server.

Possible approach

Can you somehow (other than from the hypermedia response) get a list of the superset of actions for the resource? e.g.: for your forum resource, the superset might be:

   "comment"

   "delete"

   "close"

   "next"

   "admin"

   "stats"

Maybe you could pull this list from your hypermedia-savvy design tool?

Then you use this list, not the hypermedia controls, to render the menu, leaving all items disabled.

Once the menu is created, run over it again and enable only those items that appear in the hypermedia response.

That would solve one part of your problem, i.e. showing users the options that are not available as well as those that are.

As to the other part, explaining exactly why menu item A is disabled rather than enabled, you might want to handle that some other way, and on demand only.

It could be quite expensive calculating that sort of information, especially if (as some people believe), typical user behaviour is just to shrug at the disabled menu item and move on. You probably don't want to take the performance hit every time just in case some user wonders why menu item XY2 is unavailable.

[Kijana Woodard]

Interesting. Could you expand on why you think including transitions that are not currently possible for the resource as "almost an anti-pattern for HATEOAS"?

The upside would be:

1. You don't have to check for rel presence on the resource. If it's not there now, it won't be later [exclusive of versioning].

2. It's discoverable. You don't have to bounce back and forth between the docs and the resource.

3. The docs can't diverge from the resource [with regard to rel existence].

Fwiw, I'm quite willing to accept, perhaps even predisposed towards, a separate "meta resource", but I've stumbled across the opposing view recently and I want to give it due consideration.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[erewhon]

Thanks for the replies!

On Monday, March 23, 2015 at 4:17:55 AM UTC-4, Andrew Braae wrote:

It sounds that what you want is almost an anti-pattern for HATEOAS, where all future actions the client may take (not "might ever take") are discovered within resource representations returned from the server.

This is interesting -- can you elaborate?  I think I'm considering the hypermedia controls in a way that is consistent with HATEOAS, at least in that I'm exposing links that reflect the possible, valid transitions.  I was just curious if there is a way to further communicate why a control isn't always available (it could be a separate resource).  I think it's an interesting pattern because it could be used as a means for guiding the user (e.g. "to comment here, you must be a registered user" or "to reply you must have 100 karma", etc).  I have to evaluate these transitions on the server already, so I don't think this calculation is prohibitively expensive.

[Jack Repenning]

On Mar 23, 2015, at 1:17 AM, Andrew Braae <abr...@talentappstore.com> wrote:

It sounds that what you want is almost an anti-pattern for HATEOAS, where all future actions the client may take (not "might ever take") are discovered within resource representations returned from the server.

Perhaps. On the other hand, an even more fundamental well-spring of HATEOAS is "learn from the successes of HTTP, HTML, and Web." And one thing we can learn from the history (both successful and otherwise!) of UI design is: there is no consensus on whether currently unavailable commands should be disabled/grayed, or completely suppressed! With apologies to GBS and Lerner&Lowe, "A UI designer's way of disabling absolutely classifies him: the moment he disables, he makes some *other* designer despise him!"

So, without calling a winner in that war, I will just say that, if you choose the gray/disable path, then HATEOS would teach you that the resources you're modeling (the menu picks) have an additional property you appear to have neglected: the server-side business logic imposes on the client-side application state the additional property "isDisabled". The HATEOAS protocol would have the server serve up this property along with the various others, leaving the client-side representation ("RE" in "REST") to store ("S") the state so-transferred ("T") -- where, for an h2m API, "store" generally means "in URLs generated into the web page, to be GETed ("GOT"?) if the user clicks 'em."

-- 
Jack Repenning
Repenni...@gmail.com

[Andrew Braae]

If HATEOAS is the discovery of valid transitions for a resource, then learning about invalid transitions would be an anti-pattern, was my thinking.

Splitting hairs and arguing about the meaning of ill-defined acronyms aside, it sounds like a nice approach, for all of the reasons you mention.