Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
>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.
On Thu, Oct 2, 2014 at 12:47 PM, Jay Pipes wrote:
> On 10/02/2014 03:14 PM, Chris Friesen wrote:
>
>> On 10/01/2014 12:37 PM, Jay Pipes wrote:
>>
>> 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...
>
> 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.
>
> >, 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
> OpenStack-dev@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
--
Kevin Benton
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
On 10/02/2014 01:47 PM, Jay Pipes wrote:
On 10/02/2014 03:14 PM, Chris Friesen wrote:
On 10/01/2014 12:37 PM, Jay Pipes wrote:
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.
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
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
On 10/02/2014 03:14 PM, Chris Friesen wrote:
On 10/01/2014 12:37 PM, Jay Pipes wrote:
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...
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.
>, 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
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
On 10/01/2014 12:37 PM, Jay Pipes wrote:
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
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
On 10/02/2014 11:14 AM, Jay Pipes wrote: On 10/02/2014 11:23 AM, Jay S. Bryant wrote: 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 OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev Thanks for the clarification. I think the proposal is a good idea. -theotherjay ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
On 10/02/2014 11:23 AM, Jay S. Bryant wrote: 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 OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
[Lurker popping up to get whacked :-)] >>>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 ² A status is what others conclude about a resource: ³The resource's status is ² 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 ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
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:
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.
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 th
Re: [openstack-dev] [Horizon] [All?] "Status" vs "State"
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
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [Horizon] [All?] "Status" vs "State"
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
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
