Good questions!

Jay, I have a request for some clarification in-line.

On 10/01/2014 01:37 PM, Jay Pipes wrote:
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:

# 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.

As I re-read this I think maybe you have answered my question but want to be clear. You feel that 'State' is the only term that should be used. Based on the definitions above, that would make sense. The complication is there are may places in the code where a variable like 'status' is used. Don't think we are going to be able to go back and fix all those, but it would be something that is good to watch for in reviews in the future.
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.


OpenStack-dev mailing list

OpenStack-dev mailing list

Reply via email to