"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/source/contributor/api_change_tutorial.rst" between
keystone-17.0.0.tar.gz and keystone-18.0.0.tar.gz

About: OpenStack Keystone (Core Service: Identity) provides an authentication and authorization service for other OpenStack services. Provides a catalog of endpoints for all OpenStack services.
The "Victoria" series (latest release).

api_change_tutorial.rst  (keystone-17.0.0):api_change_tutorial.rst  (keystone-18.0.0)
skipping to change at line 79 skipping to change at line 79
In this section, let's assume that a specification proposing the addition of a In this section, let's assume that a specification proposing the addition of a
`description` field to the roles API was accepted. In the next subsections, you `description` field to the roles API was accepted. In the next subsections, you
will find a detailed explanation on the needed code changes to the keystone will find a detailed explanation on the needed code changes to the keystone
code to implement such change. code to implement such change.
Architectural Recapitulation Architectural Recapitulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As you saw in the :doc:`../getting-started/architecture` document, there are As you saw in the :doc:`../getting-started/architecture` document, there are
four logical levels of code at which a successful request calls: router, three logical levels of code at which a request passes: the API routing and
controller, manager and request handling layer, the resource manager, and the driver.
driver.
For the role backend, the API resource can be found under the `keystone/api`
For the role backend, they can be found in the directory `keystone/assignment`, directory in the `roles.py` file, and the manager and driver can be found in
in the following paths, respectively: `routers.py`, `controllers.py`, `core.py` the `keystone/assignment` directory in the `core.py` and `role_backends/sql.py`
and `role_backends/sql.py` (currently only the SQL driver is supported). files, respectively (currently only the SQL driver is supported).
Changing the SQL Model and Driver Changing the SQL Model and Driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First, you need to change the role model to include the description attribute. First, you need to change the role model to include the description attribute.
Go to `keystone/assignment/role_backends/sql.py` and update it like:: Go to `keystone/assignment/role_backends/sql.py` and update it like::
class RoleTable(sql.ModelBase, sql.ModelDictMixin): class RoleTable(sql.ModelBase, sql.ModelDictMixin):
attributes = ['id', 'name', 'domain_id', 'description'] attributes = ['id', 'name', 'domain_id', 'description']
skipping to change at line 131 skipping to change at line 131
Changing the role driver itself in `keystone/assignment/role_backends/sql.py` Changing the role driver itself in `keystone/assignment/role_backends/sql.py`
will not be necessary, because the driver handles the role entities as Python will not be necessary, because the driver handles the role entities as Python
dictionaries, thus the new attribute will be handled automatically. dictionaries, thus the new attribute will be handled automatically.
Changing the Manager Changing the Manager
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
Managers handle the business logic. Keystone provides the basic CRUD for role 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 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 arguments received from the API resource, and then returns the driver's result
back to controller. Additionally, it handles the cache management. back to API resource. Additionally, it handles the cache management.
Thus, there is no manager change needed to make it able to operate role Thus, there is no manager change needed to make it able to operate role
entities with the new `description` attribute. entities with the new `description` attribute.
However, you should add tests for the role CRUD operations with the new However, you should add tests for the role CRUD operations with the new
attribute to `keystone/tests/unit/assignment/test_core.py`. attribute to `keystone/tests/unit/assignment/test_core.py`.
When trying to determine whether a change goes in the driver or in the manager, When trying to determine whether a change goes in the driver or in the manager,
the test is whether the code is business logic and/or needs to be executed for 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 each driver. Both common and business logics go in the manager, while backend
specific logic goes in the drivers. 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 Business logic should not go in the API resource. The API resource should be
as a binding between the business logic and the HTTP protocol. Thus, it is in viewed as a binding between the business logic and the HTTP protocol. Thus, it i
s in
charge of calling the appropriate manager call and wrapping responses into HTTP charge of calling the appropriate manager call and wrapping responses into HTTP
format. format.
Controllers use JSON schemas do determine whether a provided role is a valid API resource use JSON schemas do determine whether a provided role is a
representation or not. Role create and role update schemas are available at valid representation or not. Role create and role update schemas are available a
`keystone/assignment/schema.py`. t
`keystone/assignment/schema.py`. You will need to update their properties to
You will need to update their properties to include a `description` attribute:: include a `description` attribute::
_role_properties = { _role_properties = {
'name': parameter_types.name, 'name': parameter_types.name,
'description': parameter_types.description '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 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, 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:: the role routes do not need to be changed; i.e the routes still are::
POST /v3/roles POST /v3/roles
GET /v3/roles/{id} GET /v3/roles/{id}
HEAD /v3/roles/{id} HEAD /v3/roles/{id}
PATCH /v3/roles/{id} PATCH /v3/roles/{id}
DELETE /v3/roles/{id} DELETE /v3/roles/{id}
 End of changes. 7 change blocks. 
20 lines changed or deleted 26 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)