Open Stack

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 the list of stuff that really should be 
> cleaned up with an API working group.
>
> Best,
> -jay
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev