openstack
/
keystone
Code Issues Proposed changes

Merge "Update keystone Making an API Change doc"

This commit is contained in:
Zuul 2020-05-26 18:33:02 +00:00 committed by Gerrit Code Review
parent 18f96a8a3e a483f1c2c6
commit 73a66464f3
1 changed files with 23 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
doc/source/contributor/api_change_tutorial.rst
View File

@ -76,13 +76,13 @@ Architectural Recapitulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As you saw in the :doc:`../getting-started/architecture` document, there are
four logical levels of code at which a successful request calls: router,
controller, manager and
driver.
three logical levels of code at which a request passes: the API routing and
request handling layer, the resource manager, and the driver.
For the role backend, they can be found in the directory `keystone/assignment`,
in the following paths, respectively: `routers.py`, `controllers.py`, `core.py`
and `role_backends/sql.py` (currently only the SQL driver is supported).
For the role backend, the API resource can be found under the `keystone/api`
directory in the `roles.py` file, and the manager and driver can be found in
the `keystone/assignment` directory in the `core.py` and `role_backends/sql.py`
files, respectively (currently only the SQL driver is supported).
Changing the SQL Model and Driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -128,8 +128,8 @@ Changing the Manager
Managers handle the business logic. Keystone provides the basic CRUD for role
entities, that means that the role manager simply calls the driver with the
arguments received from the controller, and then returns the driver's result
back to controller. Additionally, it handles the cache management.
arguments received from the API resource, and then returns the driver's result
back to API resource. Additionally, it handles the cache management.
Thus, there is no manager change needed to make it able to operate role
entities with the new `description` attribute.
@ -142,28 +142,32 @@ the test is whether the code is business logic and/or needs to be executed for
each driver. Both common and business logics go in the manager, while backend
specific logic goes in the drivers.
Changing the Controller and Router
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changing the API Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~
Business logic should not go in the controller. The controller should be viewed
as a binding between the business logic and the HTTP protocol. Thus, it is in
Business logic should not go in the API resource. The API resource should be
viewed as a binding between the business logic and the HTTP protocol. Thus, it is in
charge of calling the appropriate manager call and wrapping responses into HTTP
format.
Controllers use JSON schemas do determine whether a provided role is a valid
representation or not. Role create and role update schemas are available at
`keystone/assignment/schema.py`.
You will need to update their properties to include a `description` attribute::
API resource use JSON schemas do determine whether a provided role is a
valid representation or not. Role create and role update schemas are available at
`keystone/assignment/schema.py`. You will need to update their properties to
include a `description` attribute::
_role_properties = {
'name': parameter_types.name,
'description': parameter_types.description
}
Besides doing the entity validation using such schemas, controllers pass and
Besides doing the entity validation using such schemas, API resource pass and
accept all the attributes to and from the manager. Thus, there is no further
change needed at the controller level.
change needed at the API resource level.
You should add tests for API unit test to `keystone/tests/unit/test_v3_role.py`
and document about the new parameter in the `api-ref`_.
.. _api-ref: https://docs.openstack.org/api-ref/identity/
Furthermore, as role entities are passed in the request body to keystone calls,
the role routes do not need to be changed; i.e the routes still are::