diff --git a/doc/source/contributor/api_change_tutorial.rst b/doc/source/contributor/api_change_tutorial.rst
index fd6cebed6b..90ef8a33b9 100644
--- a/doc/source/contributor/api_change_tutorial.rst
+++ b/doc/source/contributor/api_change_tutorial.rst
@@ -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::