Consistent service method names

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.

Separate service client modules for each resource

Some service clients contain the methods for multiple resources in a single module. For example, server_client module contains the methods for “/servers” and “/server_groups”. Current separation of modules are inconsistent, and this spec proposes all service client modules will be separated into a single module by each resource. In addition, current modules of service clients contain “JSON” in these names but we need to remove them. Because current service clients supports JSON only and “JSON” in these names are meaningless now.

Implementation

Assignee(s)

Primary assignee:

Other contributors:

Milestones

Target Milestone for completion:
Liberty

Work Items

  • Rename service clients’ methods based on this proposal.
  • Rename service clients’ classes based on this proposal.
  • Separate service clients’ modules per resources.
  • Add hacking rules based on this proposal.

References

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.