RFC: How Things Report Their Status

[alecho]

I'm just thinking out loud and this post is subject to change. I just wanted to get my thoughts down.

The question everyone seems to be eager to solve at our meetups is "How does a consumer know what a status means?". Often, the suggestion is to use a simple "color" (such as stoplights) or a binary system so that consuming code is easy to write. Both of these proposed systems in my view are fundamentally wrong. Although, admittedly they will solve the problem in the short term. They are flawed because colors, boolean values, and integers don't have any inherit meaning in and by themselves and some things are very boolean, such as power, while others, like HVAC follow a more floating scale of failure.

A simpler and more complete way for a consumer to find out what is wrong with a thing is to ask.

A (horrible) skit between the API and A consumer may transact as follows:

Consumer: Is the internet at OpenWorks functioning as expected?
API: No.
C: Why isn't the internet functioning as expected?
A: DNS lookups are failing.
C: I don't understand what that means. How severe is this issue?
A: On a scale of 1-10, 5.
C: When did this issues start?
A: About 15 minutes ago.
C: Is there anything I should tell my users?
A: You can tell them, "The ISP is having DNS issues, this will only affect users who do not have their own DNS preference set."

What I hope this illustrates is that a status is not a single thing but rather a collection of things. Obviously, a consumer wouldn't necessarily make multiple requests to receive all of this information. The key is that a consumer just needs to know if it should ask.

I'm proposing a flag field such as is_failing on the thing model or it's subclasses that informs a consumer if it should check for more information, although the consumer is not required to.

[allella]

I don't know a heck of a lot about Hypermedia APIs, but this sounds sort of like the purpose of what many of the RESTfest folks talk about. Basically a REST API that returns data, but also hyperlinks for what you can do next.

[alecho]

Yes. To be clear I don't think multiple requests should be made for the information. More simply, what I'm suggesting is that a thing has one status. If thing.status_id is NULL then we can assume that everything is functioning as expecting with thing. Otherwise the related status has all of the details.

This gets tricky with items that have a constant "status" like things with a temperature.