Add consistent-service-method-names spec
This patch adds consistent-service-method-names spec Partially implements blueprint consistent-service-method-names Change-Id: Icae7cbbb9aabb94bc80ee0f35b868b0472d79ed4
This commit is contained in:
Ken'ichi Ohmichi
parent
117070bbaa
commit
1ffd92acbb
|
|
@ -0,0 +1,147 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
..
|
||||
|
||||
===============================
|
||||
Consistent service method names
|
||||
===============================
|
||||
|
||||
https://blueprints.launchpad.net/tempest/+spec/consistent-service-method-names
|
||||
|
||||
Make service method names consistent
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
Service clients are Tempest own REST clients for operating each OpenStack
|
||||
project's APIs. And we have a plan to migrate service clients' methods to
|
||||
tempest-lib.
|
||||
However these methods' names are inconsistent, and it would be difficult
|
||||
to use these methods from viewpoint of library users.
|
||||
So we need to make these names consistent and set up the way to keep them
|
||||
consistent before migrating.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Basically all methods' names should be "<verb>_<resource/object name>", not
|
||||
"<resource/object name>_<verb>".
|
||||
There are following patterns we need to consider method names for REST API
|
||||
methods.
|
||||
|
||||
* POST /resources (Create a resource)
|
||||
* PUT /resources/<id> (Update a resource)
|
||||
* DELETE /resources/<id> (Delete a resource)
|
||||
* GET /resources (Get a list of resources)
|
||||
* GET /resources/<id> (Get the detail information of a resource)
|
||||
|
||||
https://etherpad.openstack.org/p/tempest-consistent-service-method-names is
|
||||
an investigation of current method names. Based on the investigation, this
|
||||
spec proposes consistent method names of each patterns. In addition, this
|
||||
proposes hacking checks for keeping consistent method names. The patch
|
||||
https://review.openstack.org/168762 is a prototype for these hacking checks.
|
||||
The details of them are following.
|
||||
|
||||
POST /resources
|
||||
---------------
|
||||
|
||||
Naming rule: "create_<resource name>"
|
||||
|
||||
All creation methods follow this rule, so we don't need to rename creation
|
||||
methods. The hacking check of this rule is "If a method calls self.post(),
|
||||
the method name should be create_<resource name>".
|
||||
|
||||
PUT /resources/<id>
|
||||
-------------------
|
||||
|
||||
Naming rule: "update_<resource name>"
|
||||
|
||||
All update methods follow this rule, so we don't need to rename update methods.
|
||||
The hacking check of this rule is "If a method calls self.put(), the method
|
||||
name should be update_<resource name>".
|
||||
|
||||
DELETE /resources/<id>
|
||||
----------------------
|
||||
|
||||
Naming rule: "delete_<resource name>"
|
||||
|
||||
There are two patterns for deletion method, "delete_<resource name>" and
|
||||
"remove_<resource name>". The number of "delete_<resource name>" is 72, and
|
||||
the one of the other is 11. In addition, "delete_<resource name>" is simple
|
||||
name because it is the same as HTTP method. The hacking check of this rule is
|
||||
"If a method calls self.delete(), the method name should be delete_<resource
|
||||
name>".
|
||||
|
||||
GET /resources
|
||||
--------------
|
||||
|
||||
Naming rule: "list_<resource name>s"
|
||||
|
||||
There are three patterns for listing resources, "list_<resource name>s",
|
||||
"get_<resource name>_list" and "<resource name>_list". The number of the
|
||||
first is 115, the one of the second is 3 and the one of the third is 2.
|
||||
|
||||
Some Nova APIs provide a resource list with detail information like
|
||||
'os-hypervisors/detail' and 'os-availability-zone/detail'. These method names
|
||||
are get_hypervisor_list_details and get_availability_zone_list_detail now.
|
||||
This spec proposes these methods are merged to this naming rule like::
|
||||
|
||||
list_availability_zones(self, detail=False):
|
||||
url = 'os-availability-zone'
|
||||
if detail:
|
||||
url += '/detail'
|
||||
resp, body = self.get(url)
|
||||
..
|
||||
|
||||
by adding the argument detail.
|
||||
"GET /resources" and "GET /resources/<id>" call the same method self.get()
|
||||
for sending a request to servers. So it is difficult to check the methods
|
||||
which call self.get() should be based on rules of "GET /resources" or "GET
|
||||
/resources/<id>". Then this spec proposes the same hacking check for
|
||||
"GET /resources" or "GET /resources/<id>". That means the hacking check is
|
||||
"If a method calls self.get(), the method name should be show_<resource name>
|
||||
or list_<resource name>s.
|
||||
|
||||
GET /resources/<id>
|
||||
-------------------
|
||||
|
||||
Naming rule: "show_<resource name>"
|
||||
|
||||
There are two patterns for getting the detail of a resource, "show_<resource
|
||||
name>" and "get_<resource name>". The number of the first is 12, and the one
|
||||
of the second is 126. So the number of the second is bigger.
|
||||
However, this spec proposes all "GET /resources/<id>" methods should be named
|
||||
to "show_<resource name>" because of clarifying differences from methods which
|
||||
are for "GET /resources". There are methods for "GET /resources" also and some
|
||||
resource names are the same between a single noun and multiple nouns like
|
||||
"chassis". So it is better to avoid using "get_<resource name>" for clarifying
|
||||
the method behavior. The hacking check of this rule is mentioned at the above.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
|
||||
* Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp>
|
||||
|
||||
Other contributors:
|
||||
|
||||
* Masayuki Igawa <igawa@mxs.nes.nec.co.jp>
|
||||
|
||||
Milestones
|
||||
----------
|
||||
|
||||
Target Milestone for completion:
|
||||
Liberty
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
* Rename service clients' methods based on this proposal.
|
||||
* Add hacking rules based on this proposal.
|
||||
Loading…
Reference in New Issue