[openstack-dev] [Horizon] [All?] "Status" vs "State"

[Akihiro Motoki]

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

Thanks,
Akihiro

[Jay Pipes]

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 :)

Post by Akihiro Motoki
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

[Jay S. Bryant]

Good questions!

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

Post by Jay Pipes
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 :)

Post by Akihiro Motoki
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,
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.

Post by Jay Pipes
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.
* 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
_______________________________________________
OpenStack-dev mailing list
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[Jay Pipes]

Post by Jay S. Bryant
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.

I'm talking about new versions of the public APIs that get proposed, not
existing ones. Within the codebase, it would be great to use a single
term "state" for this, prefixed with a refining descriptor like
"power_", "task_", etc. But that's a lesser concern for me than our next
generation REST APIs.

Best,
-anotherjay

[Jay S. Bryant]

Post by Jay Pipes

Post by Jay S. Bryant
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.

I'm talking about new versions of the public APIs that get proposed,
not existing ones. Within the codebase, it would be great to use a
single term "state" for this, prefixed with a refining descriptor like
"power_", "task_", etc. But that's a lesser concern for me than our
next generation REST APIs.
Best,
-anotherjay
_______________________________________________
OpenStack-dev mailing list
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Thanks for the clarification. I think the proposal is a good idea.

-theotherjay

[Chris Friesen]

Post by Jay Pipes
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". :(

Hi Jay,

I wonder if this would tie into our other discussion about
distinguishing between the "desired state" vs the "actual state".
Conceivably you could have the "admin state" be UP, but a fault has
resulted in an "actual state" other than "ACTIVE".

As a reference point, CCITT X.731 goes into huge detail about state and
status. They define three orthogonal types of state (operational,
usage, and administrative), and many types of status (availability,
alarm, control, etc.) I'm not suggesting that OpenStack should use
those exact terms, but it suggests that some people have found it useful
to have state along multiple axes rather than trying to stuff everything
into a single variable.

Chris

[Jay Pipes]

Post by Chris Friesen

Post by Jay Pipes
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". :(

Hi Jay,
I wonder if this would tie into our other discussion about
distinguishing between the "desired state" vs the "actual state".
Conceivably you could have the "admin state" be UP, but a fault has
resulted in an "actual state" other than "ACTIVE".

My comment above was about the inconsistency of how things are named and
the data types representing them. There is a status field of type
string, and an admin_state_up field of type boolean, both in the same
response. Why wasn't it called admin_state and made a string field to
follow the convention of the status field? I'm guessing it probably has
to do with the telecom IT recommendations you cite below...

Post by Chris Friesen
As a reference point, CCITT X.731 goes into huge detail about state and
status. They define three orthogonal types of state (operational,
usage, and administrative), and many types of status (availability,
alarm, control, etc.) I'm not suggesting that OpenStack should use
those exact terms

The very last thing I believe OpenStack should use as a reference is
anything the telecommunications IT industry has put together as a
recommendation.

If we do use telecom IT as a guide, we'll be in a worse state (pun
intended), ease-of-use and user-friendliness-wise, than we already are,
and literally every API will just be a collection of random three and
four letter acronyms with nobody other than a veteran network engineer
understanding how anything works.

In other words, all our APIs would look like the Neutron API as it
exists today.

Post by Chris Friesen
, but it suggests that some people have found it useful
to have state along multiple axes rather than trying to stuff everything
into a single variable.

I'm not opposed to using multiple fields to indicate state; I thought I
was pretty clear about that in my initial response?

Best,
-jay

[Chris Friesen]

Post by Jay Pipes

Post by Chris Friesen

Post by Jay Pipes
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". :(

Hi Jay,
I wonder if this would tie into our other discussion about
distinguishing between the "desired state" vs the "actual state".
Conceivably you could have the "admin state" be UP, but a fault has
resulted in an "actual state" other than "ACTIVE".

My comment above was about the inconsistency of how things are named and
the data types representing them. There is a status field of type
string, and an admin_state_up field of type boolean, both in the same
response. Why wasn't it called admin_state and made a string field to
follow the convention of the status field? I'm guessing it probably has
to do with the telecom IT recommendations you cite below...

Sorry, I misread your statement to mean that there should be only a
single state field rather than a comment on the type of the variable.

The telecom administrative state values are "locked", "unlocked", and
"shutting down", so it seems unlikely that they would be the impetus for
the Neutron values.

Post by Jay Pipes
If we do use telecom IT as a guide, we'll be in a worse state (pun
intended), ease-of-use and user-friendliness-wise, than we already are,
and literally every API will just be a collection of random three and
four letter acronyms with nobody other than a veteran network engineer
understanding how anything works.
In other words, all our APIs would look like the Neutron API as it
exists today.

:)

Chris

[Kevin Benton]

In other words, all our APIs would look like the Neutron API as it exists

today.

That's a bad comparison because the Neutron API doesn't have a standard
that it follows at all. If there was a standard for states/statuses that
Neutron was following for all of the objects, the status of the Neutron API
today would be in a much less annoying state.

Post by Jay Pipes
IMO, the term "state" should be the only one used in the OpenStack APIs

Post by Jay Pipes
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". :(

Hi Jay,
I wonder if this would tie into our other discussion about
distinguishing between the "desired state" vs the "actual state".
Conceivably you could have the "admin state" be UP, but a fault has
resulted in an "actual state" other than "ACTIVE".

My comment above was about the inconsistency of how things are named and
the data types representing them. There is a status field of type string,
and an admin_state_up field of type boolean, both in the same response. Why
wasn't it called admin_state and made a string field to follow the
convention of the status field? I'm guessing it probably has to do with the
telecom IT recommendations you cite below...
As a reference point, CCITT X.731 goes into huge detail about state and

Post by Jay Pipes
status. They define three orthogonal types of state (operational,
usage, and administrative), and many types of status (availability,
alarm, control, etc.) I'm not suggesting that OpenStack should use
those exact terms

The very last thing I believe OpenStack should use as a reference is
anything the telecommunications IT industry has put together as a
recommendation.
If we do use telecom IT as a guide, we'll be in a worse state (pun
intended), ease-of-use and user-friendliness-wise, than we already are, and
literally every API will just be a collection of random three and four
letter acronyms with nobody other than a veteran network engineer
understanding how anything works.
In other words, all our APIs would look like the Neutron API as it exists
today.

Post by Jay Pipes
, but it suggests that some people have found it useful
to have state along multiple axes rather than trying to stuff everything
into a single variable.

I'm not opposed to using multiple fields to indicate state; I thought I
was pretty clear about that in my initial response?
Best,
-jay
_______________________________________________
OpenStack-dev mailing list
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[John Plocher]

[Lurker popping up to get whacked :-)]

Post by Jay Pipes

both "State" (admin_state_up) and "Status² are usually used in Neutron
resources...
but it seems the meaning of "State" and "Status" are reversed...
I am really confused what is the right usage of these words....

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"

If it helps, ³state² many times is conceptually an attribute closely
attached to, or part of an item, while ³status² tends to be an attribute
applied by others to the item. State feels more like an absolute, while
status feels more contextual, fluid or consensus based.

I tend to use the terms thus:

A state is what a resource consider itself to be:
³Change the state of this resource to <disabled>²

A status is what others conclude about a resource:
³The resource's status is <not responding to requests>²

For this discussion, the desired concept seems to be more the precise,
³comp sci state machine² one. The context where the term is used implies
(at least to me) an assumption of absoluteness or active control and not
simply a passive interpretation of behavior.

To me this says ³state² is the right choice :-)

-John