Open Stack

Hi Akihiro!

IMO, this is precisely where having an API standards working group can 
help to make the user experience of our public APIs less frustrating. 
Such a working group should have the ability to vet terms like "state" 
vs "status" and ensure consistency across the public APIs.

More thoughts inline :)

On 10/01/2014 11:24 AM, Akihiro Motoki wrote:
> Hi,
>
> # The first half is related to Horizon and the latter half is about
> the wording in Nova and Neutron API.
>
> During Horizon translation for Juno, I noticed the words "State" and
> "Status" in multiple contexts. Sometimes they are in very similar
> contexts and sometimes they have different contexts.
>
> I would like to know what are the difference between  "Status" and
> "State", and if the current usage is right or not, whether we can
> reword them. Input from native speakers would be really appreciated.
>
> I see three usages.
>
> (1) "Status" to show operational status (e.g. Up/Down/Active/Error/Build/...)
> (2) "Status" to show administrative status (e.g. Enabled/Disabled/...)
> (3) "State" to show operational state (e.g., Up/Down/....)
>
> Note that (2) and (3) are shown in a same table (for example Compute
> Host table in Hypervisor summary). Also (1) and (3) (e.g., task state
> in nova) are used in a same table (for example, the instance table).
>
> "Status" in (1) and (2) have different meaning to me, so at least
> we need to add some contextual note ("contextual marker" in I18N term)
> so that translators can distinguish (1) and (2).
>
> Related to this, I check Nova and Neutron API, and
> I don't see a clear usage of these words.
>
> In Nova API, "Status" and "Task State"/"Power State" in instance list
>   are both used to show current operational information ("state" is a
> bit more detail
> information compared to "Status"). On the other hand, in service lits
> "Status" is used to show a current administrative status
> (Enabled/Disabled) and "State" is used to show current operational
> information like Up/Down.
>
> In Neutron API, both "State" (admin_state_up)  and "Status" are
> usually used in Neutron resources (networks, ports, routers, and so
> on), but it seems the meaning of "State" and "Status" are reversed
> from the meaning of Nova service list above.
>
> I am really confused what is the right usage of these words....

OK, so here are the definitions of these terms in English (at least, the 
relevant definition as used in the APIs...):

state: the particular condition that someone or something is in at a 
specific time.

example: "the state of the company's finances"

status: the position of affairs at a particular time, especially in 
political or commercial contexts.

example: "an update on the status of the bill"

Note that "state" is listed as a synonym for "status", but "status" is 
*not* listed as a synonym for "state", which is why there is so much 
frustrating vagueness and confusing duplicity around the terms.

IMO, the term "state" should be the only one used in the OpenStack APIs 
to refer to the condition of some thing at a point in time. The term 
"state" can and should be prefaced with a refining descriptor such 
"task" or "power" to denote the *thing* that the state represents a 
condition for.

One direct change I would make would be that Neutron's "admin_state_up" 
field would be instead "admin_state" with values of UP, DOWN (and maybe 
UNKNOWN?) instead of having the *same* GET /networks/{network_id} call 
return *both* a boolean "admin_state_up" field *and* a "status" field 
with a string value like "ACTIVE". :(

Another thing that drives me crazy is the various things that represent 
enabled or disabled.

Throughout the APIs, we use, variably:

  * A field called disabled or enabled (Nova flavor-disabled API 
extension with the "OS-FLV-DISABLED:disabled" attribute, Ceilometer 
alarms, Keystone domains, users and projects but not groups or credentials)
  * enable_XXX or disable_XXX (for example, in Neutron's GET 
/subnets/{subnet_id} response, there is an enable_dhcp field. In Heat's 
GET /stacks/{stack_id} response, there is a disable_rollback field. We 
should be consistent in using either the word enable or the word disable 
(not both terms) and the tense of the verb should at the very least be 
consistent (disabled vs. disable))
  * status:disabled (Nova os-services API extension. The service records 
have a status field with "disabled" or "enabled" string in it. Gotta 
love it.)

Yet another thing to tack on the list of stuff that really should be 
cleaned up with an API working group.

Best,
-jay