Re: [openstack-dev] [all] REST API style guide (Re: [Nova] Some ideas for micro-version implementation)
On Tue, 23 Sep 2014 09:00:26 +0900 Ken'ichi Ohmichi ken1ohmi...@gmail.com wrote: \ So how about just using HTTP 200(OK) only for status codes? That would give up providing accurate internal status to clients but backwards backwards incompatibilities never happen. No I think that we should where possible return the most accurate status code. A 202 versus 200 is an important distinction for a user of the API (eg do they need to poll for request completion?). How fast we can get to accurate status codes through the API is a different matter though. and I have one more idea for making API consistency of whole OpenStack projects. That is each rule of the style guide is implemented in Tempest. Tempest has its own REST clients for many projects and we can customize them for improving qualities. After defining the REST API style guide, we can add each rule to Tempest's base client class and apply it for all REST APIs which are tested by Tempest. We can keep consistent API for the existing projects and apply the style guide to new projects also by this framework. That's an interesting idea! However we would have a long exception list for a quite a while I think as it was made pretty clear to use we can't make a large number of backwards compatible API changes over a short period of time. (Like a v2-v3 transition was). Regards, Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] REST API style guide (Re: [Nova] Some ideas for micro-version implementation)
-Original Message- From: Alex Xu [mailto:x...@linux.vnet.ibm.com] Sent: Tuesday, September 23, 2014 12:20 PM To: OpenStack Development Mailing List (not for usage questions) Subject: Re: [openstack-dev] [all] REST API style guide (Re: [Nova] Some ideas for micro-version implementation) Before discussing how to implement, I'd like to consider what we should implement. IIUC, the purpose of v3 API is to make consistent API with the backwards incompatible changes. Through huge discussion in Juno cycle, we knew that backwards incompatible changes of REST API would be huge pain against clients and we should avoid such changes as possible. If new APIs which are consistent in Nova API only are inconsistent for whole OpenStack projects, maybe we need to change them again for whole OpenStack consistency. For avoiding such situation, I think we need to define what is consistent REST API across projects. According to Alex's blog, The topics might be - Input/Output attribute names - Resource names - Status code The following are hints for making consistent APIs from Nova v3 API experience, I'd like to know whether they are the best for API consistency. (1) Input/Output attribute names (1.1) These names should be snake_case. eg: imageRef - image_ref, flavorRef - flavor_ref, hostId - host_id (1.2) These names should contain extension names if they are provided in case of some extension loading. eg: security_groups - os-security-groups:security_groups config_drive - os-config-drive:config_drive Do you mean that the os- prefix should be dropped? Or that it should be maintained and added as needed? The above samples contain two meanings: - extension names are added. (os-security-groups:, os-config-drive:) - their extensions are not cores. (v3 ones should contain os-) Their changes are Nova v3 API's ones, and now I have a question related to your point. Should we add extension names to each input/output attribute names? How about naming them with snake_case only without extension names? I can think out of two purposes for add extension names to attribute names. One is used for namespace, Another one is used for distinguish between core and extension. Is the namespace for avoiding duplicated attribute names? Actually, I could not find duplicated names on current v2 api if removing extension names from attributes. And with extension name is more readable for developer, developer can know this attribute come from which extension without search API doc. Yeah, that is true. That is one merit of extension names. but I'd like to know that is common thing on whole OpenStack projects. To be honest, I'm not sure yet extension name values for each attribute name. Additional extension names make attribute names long and complex. In addition, if we define Pecan/WSME as standard web frameworks, we should name attributes with snake_case only because of Pecan/WSME restriction[1]. So we can not name them with hyphens and colons which are including in current extension attribute names. yes, good point, that is problem. Is it only restriction for resource-name? -/: works for getattr/setattr, it is a walk around, so I'm not sure it's worth. The restriction works for both resource-name and attribute name also. (1.3) Extension names should consist of hyphens and low chars. eg: OS-EXT-AZ:availability_zone - os-extended-availability-zone:availability_zone OS-EXT-STS:task_state - os-extended-status:task_state Yes, I don't like the shoutyness of the ALL CAPS. (1.4) Extension names should contain the prefix os- if the extension is not core. eg: rxtx_factor - os-flavor-rxtx:rxtx_factor os-flavor-access:is_public - flavor-access:is_public (flavor-access extension became core) Do we have a list of core yet? We have the list in the code: nova/api/openstack/__init__.py 62 # List of v3 API extensions which are considered to form 63 # the core API and so must be present 64 # TODO(cyeoh): Expand this list as the core APIs are ported to V3 65 API_V3_CORE_EXTENSIONS = set(['consoles', 66 'extensions', 67 'flavor-extra-specs', 68 'flavor-manage', 69 'flavors', 70 'ips', 71 'os-keypairs', 72 'os-flavor-access', 73 'server-metadata', 74 'servers', 75 'versions']) # As you see, some extensions in the above list contains os- even if cores # because we have reverted them to v2 names through v2.1 API development. but here also I have a question. Is it necessary to define core by itself? IIUC
Re: [openstack-dev] [all] REST API style guide (Re: [Nova] Some ideas for micro-version implementation)
-Original Message- From: Christopher Yeoh [mailto:cbky...@gmail.com] Sent: Tuesday, September 23, 2014 7:50 PM To: OpenStack Development Mailing List (not for usage questions) Subject: Re: [openstack-dev] [all] REST API style guide (Re: [Nova] Some ideas for micro-version implementation) On Tue, 23 Sep 2014 09:00:26 +0900 Ken'ichi Ohmichi ken1ohmi...@gmail.com wrote: So how about just using HTTP 200(OK) only for status codes? That would give up providing accurate internal status to clients but backwards backwards incompatibilities never happen. No I think that we should where possible return the most accurate status code. A 202 versus 200 is an important distinction for a user of the API (eg do they need to poll for request completion?). How fast we can get to accurate status codes through the API is a different matter though. Yes, the most accurate status code is ideal. My point was: The most accurate status code depends on the internal implementation. If we change the implementation which affects resource status like sync - async, we should change its status code also with backwards incompatibility, right? and I have one more idea for making API consistency of whole OpenStack projects. That is each rule of the style guide is implemented in Tempest. Tempest has its own REST clients for many projects and we can customize them for improving qualities. After defining the REST API style guide, we can add each rule to Tempest's base client class and apply it for all REST APIs which are tested by Tempest. We can keep consistent API for the existing projects and apply the style guide to new projects also by this framework. That's an interesting idea! However we would have a long exception list for a quite a while I think as it was made pretty clear to use we can't make a large number of backwards compatible API changes over a short period of time. (Like a v2-v3 transition was). That is a nice point. My idea is that * The base REST client class contains all style checks with each version for using all projects. * Nova base REST client class inherits from the above class and specifies microversions for each style check. The code would be: class BaseRestClient(object): version_style_rule_01 = None version_style_rule_02 = None [..] def post(self, url, req_body, version=None ..): # Check request body style if version_style_rule_01 is None or version version_style_rule_01: self.check_style_rule_01(req_body) if version_style_rule_02 is None or version version_style_rule_02: self.check_style_rule_02(req_body) [..] resp, resp_body = DO_POST_TO_EACH_PROJECT_API # Check response body style if version_style_rule_01 is None or version version_style_rule_01: self.check_style_rule_01(resp_body) if version_style_rule_02 is None or version version_style_rule_02: self.check_style_rule_02(resp_body) [..] class NovaRestClient(BaseRestClient): version_style_rule_01 = 3 version_style_rule_02 = 4 [..] As the default, all style checks are enabled. and in Nova case, we will be able to specify each microversions as version_style_rule_01/02/... Thanks Ken'ichi Ohmichi ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] REST API style guide (Re: [Nova] Some ideas for micro-version implementation)
On 2014年09月23日 08:00, Ken'ichi Ohmichi wrote: # I changed the title for getting opinions from many projects. 2014-09-22 23:47 GMT+09:00 Anne Gentle a...@openstack.org: -Original Message- From: Alex Xu [mailto:x...@linux.vnet.ibm.com] Sent: Friday, September 19, 2014 3:40 PM To: OpenStack Development Mailing List Subject: [openstack-dev] [Nova] Some ideas for micro-version implementation Close to Kilo, it is time to think about what's next for nova API. In Kilo, we will continue develop the important feature micro-version. In previous v2 on v3 propose, it's include some implementations can be used for micro-version. (https://review.openstack.org/#/c/84695/19/specs/juno/v2-on-v3-api.rst) But finally, those implementations was considered too complex. So I'm try to find out more simple implementation and solution for micro-version. I wrote down some ideas as blog post at: http://soulxu.github.io/blog/2014/09/12/one-option-for-nova-api/ And for those ideas also already done some POC, you can find out in the blog post. As discussion in the Nova API meeting, we want to bring it up to mail-list to discussion. Hope we can get more idea and option from all developers. We will appreciate for any comment and suggestion! I would greatly appreciate this style guide to be finalized for documentation purposes as well. Thanks for starting this write-up. I'd be happy to write it up on a wiki page while we get agreement, would that be helpful? The wiki page of REST API style guide would be great, thanks for joining into this :-) Yes, the REST API style guide is helpful, thanks too :) Before discussing how to implement, I'd like to consider what we should implement. IIUC, the purpose of v3 API is to make consistent API with the backwards incompatible changes. Through huge discussion in Juno cycle, we knew that backwards incompatible changes of REST API would be huge pain against clients and we should avoid such changes as possible. If new APIs which are consistent in Nova API only are inconsistent for whole OpenStack projects, maybe we need to change them again for whole OpenStack consistency. For avoiding such situation, I think we need to define what is consistent REST API across projects. According to Alex's blog, The topics might be - Input/Output attribute names - Resource names - Status code The following are hints for making consistent APIs from Nova v3 API experience, I'd like to know whether they are the best for API consistency. (1) Input/Output attribute names (1.1) These names should be snake_case. eg: imageRef - image_ref, flavorRef - flavor_ref, hostId - host_id (1.2) These names should contain extension names if they are provided in case of some extension loading. eg: security_groups - os-security-groups:security_groups config_drive - os-config-drive:config_drive Do you mean that the os- prefix should be dropped? Or that it should be maintained and added as needed? The above samples contain two meanings: - extension names are added. (os-security-groups:, os-config-drive:) - their extensions are not cores. (v3 ones should contain os-) Their changes are Nova v3 API's ones, and now I have a question related to your point. Should we add extension names to each input/output attribute names? How about naming them with snake_case only without extension names? I can think out of two purposes for add extension names to attribute names. One is used for namespace, Another one is used for distinguish between core and extension. And with extension name is more readable for developer, developer can know this attribute come from which extension without search API doc. To be honest, I'm not sure yet extension name values for each attribute name. Additional extension names make attribute names long and complex. In addition, if we define Pecan/WSME as standard web frameworks, we should name attributes with snake_case only because of Pecan/WSME restriction[1]. So we can not name them with hyphens and colons which are including in current extension attribute names. yes, good point, that is problem. Is it only restriction for resource-name? -/: works for getattr/setattr, it is a walk around, so I'm not sure it's worth. (1.3) Extension names should consist of hyphens and low chars. eg: OS-EXT-AZ:availability_zone - os-extended-availability-zone:availability_zone OS-EXT-STS:task_state - os-extended-status:task_state Yes, I don't like the shoutyness of the ALL CAPS. (1.4) Extension names should contain the prefix os- if the extension is not core. eg: rxtx_factor - os-flavor-rxtx:rxtx_factor os-flavor-access:is_public - flavor-access:is_public (flavor-access extension became core) Do we have a list of core yet? We have the list in the code: nova/api/openstack/__init__.py 62 # List of v3 API extensions which are considered to form 63 # the core API and so must be present 64 # TODO(cyeoh): Expand this list as the core APIs are
