Merge "Fix up the api-ref request/response parameters for projects"

api-ref/source/v3/parameters.yaml

@@ -255,18 +255,32 @@ nocatalog:
   in: query
   required: false
   type: string
-parent_id_2:
+parent_id_query:
   description: |
-    (Since v3.4) Filters the response by a parent ID.
+    Filters the response by a parent ID.
   in: query
   required: false
   type: string
+  min_version: 3.4
 parent_region_id_query:
   description: |
     Filters the response by a parent region, by ID.
   in: query
   required: false
   type: string
+project_enabled_query:
+  description: |
+    If set to true, then only enabled projects will be returned. Any value
+    other than ``0`` (including no value) will be interpreted as true.
+  in: query
+  required: false
+  type: boolen
+project_name_query:
+  description: |
+    Filters the response by a project name.
+  in: query
+  required: false
+  type: string
 role_id_query:
   description: |
     Filters the response by a role ID.
@@ -458,12 +472,6 @@ description_4:
   in: body
   required: false
   type: string
-description_6:
-  description: |
-    The project description.
-  in: body
-  required: true
-  type: string
 description_7:
   description: |
     The domain description.
@@ -586,12 +594,6 @@ domain_id_3:
   in: body
   required: false
   type: string
-domain_id_4:
-  description: |
-    The ID of the domain for the project.
-  in: body
-  required: true
-  type: string
 domain_id_5:
   description: |
     The ID of the domain for the group.
@@ -698,13 +700,6 @@ enabled_10:
   in: body
   required: true
   type: boolean
-enabled_13:
-  description: |
-    If set to ``true``, project is enabled. If set to
-    ``false``, project is disabled.
-  in: body
-  required: true
-  type: boolean
 enabled_2:
   description: |
     Enables or disables the project.  Users can
@@ -727,18 +722,6 @@ enabled_3:
   in: body
   required: false
   type: boolean
-enabled_5:
-  description: |
-    Enables or disables the project and its subtree.
-    Users can authorize against an enabled project.  Users cannot
-    authorize against a disabled project. All tokens that are
-    authorized for a disabled project become no longer valid. If you
-    reenable the project, these tokens are not re-enabled.  To enable
-    the project and its subtree, set to ``true``. To disable the
-    project and its subtree, set to ``false``. Default is ``true``.
-  in: body
-  required: true
-  type: boolean
 enabled_7:
   description: |
     Indicates whether the endpoint appears in the
@@ -1022,29 +1005,29 @@ interface_1:
   in: body
   required: true
   type: string
-is_domain:
+is_domain_request_body:
   description: |
-    (Since v3.6) Indicates whether the project also
+    Indicates whether the project also acts as a domain. If set to ``true``,
-    acts as a domain.  Set to ``true`` to define this project as both
+    this project acts as both a project and domain. As a domain, the project
-    a project and domain. As a domain, the project provides a name
+    provides a name space in which you can create users, groups, and other
-    space in which you can create users, groups, and other projects.
+    projects. If set to ``false``, this project behaves as a regular project
-    Set to ``false`` to define this project as a regular project that
+    that contains only resources. Default is ``false``. You cannot update
-    contains only resources.  Default is ``false``.  You cannot update
     this parameter after you create the project.
   in: body
   required: false
   type: boolean
-is_domain_1:
+  min_version: 3.6
+is_domain_response_body:
   description: |
-    (Since v3.6) Indicates whether the project also
+    Indicates whether the project also acts as a domain. If set to ``true``,
-    acts as a domain.  If set to ``true``, this project acts as both a
+    this project acts as both a project and domain. As a domain, the project
-    project and domain. As a domain, the project provides a name space
+    provides a name space in which you can create users, groups, and other
-    in which you can create users, groups, and other projects.
+    projects. If set to ``false``, this project behaves as a regular project
-    Otherwise, this field does not appear in the response and this
+    that contains only resources. 
-    project behaves as a regular project that contains only resources.
   in: body
-  required: false
+  required: true
   type: boolean
+  min_version: 3.6
 issued_at:
   description: |
     The date and time when the token was issued.
@@ -1130,12 +1113,6 @@ links_4:
   in: body
   required: true
   type: object
-links_5:
-  description: |
-    The links for the ``project`` resource.
-  in: body
-  required: true
-  type: object
 links_7:
   description: |
     The links for the ``role`` resource.
@@ -1254,13 +1231,6 @@ name_4:
   in: body
   required: true
   type: string
-name_5:
-  description: |
-    The project name, which must be unique within the
-    owning domain. The project can have the same name as its domain.
-  in: body
-  required: true
-  type: string
 name_6:
   description: |
     The role name.
@@ -1273,13 +1243,6 @@ name_7:
   in: body
   required: false
   type: string
-name_9:
-  description: |
-    The project name. The project can have the same
-    name as its domain.
-  in: body
-  required: true
-  type: string
 original_password:
   description: |
     The original password for the user.
@@ -1348,25 +1311,139 @@ policy:
   type: object
 project:
   description: |
-    A ``project`` object.
+    A ``project`` object, containing:
   in: body
   required: true
   type: object
-project_id_1:
+project_description_request_body:
   description: |
-    The UUID for the associated project.
+    The description of the project.
-  in: body
-  required: true
-  type: string
-project_id_2:
-  description: |
-    The UUID for the associated project.
   in: body
   required: false
   type: string
+project_description_response_body:
+  description: |
+    The description of the project.
+  in: body
+  required: true
+  type: string
+project_domain_id_request_body:
+  description: |
+    The ID of the domain for the project.
+
+    For projects acting as a domain, the ``domain_id`` must not be specified,
+    it will be generated by the Identity service implementation.
+
+    For regular projects (i.e. those not acing as a domain), if ``domain_id``
+    is not specified, but ``parent_id`` is specified, then the domain ID of the
+    parent will be used. If neither ``domain_id`` or ``parent_id`` is
+    specified, the Identity service implementation will default to the domain
+    to which the client's token is scoped. If both ``domain_id`` and
+    ``parent_id`` are specified, and they do not indicate the same domain, an
+    ``Bad Request (400)`` will be returned.
+  in: body
+  required: false
+  type: string
+project_domain_id_response_body:
+  description: |
+    The ID of the domain for the project.
+  in: body
+  required: true
+  type: string
+project_domain_id_update_request_body:
+  description: |
+    The ID of the new domain for the project. The ability to change the domain
+    of a project is now deprecated, and will be removed in subequent release.
+    It is already disabled by default in most Identity service implementations.
+  in: body
+  required: false
+  type: string
+project_enabled_cascade_request_body:
+  description: |
+    Enables or disables the project and its subtree.
+    Users can authorize against an enabled project, but not against a disabled
+    project. All tokens that are authorized for all projects in the affected
+    hierarchy become no longer valid. If you reenable the projects, these tokens
+    are not re-enabled.  To enable the project and its subtree, set to ``true``.
+    To disable the project and its subtree, set to ``false``.
+  in: body
+  required: true
+  type: boolean
+project_enabled_request_body:
+  description: |
+    If set to ``true``, project is enabled. If set to
+    ``false``, project is disabled. The default is ``true``.
+  in: body
+  required: false
+  type: boolean
+project_enabled_response_body:
+  description: |
+    If set to ``true``, project is enabled. If set to
+    ``false``, project is disabled.
+  in: body
+  required: true
+  type: boolean
+project_enabled_update_request_body:
+  description: |
+    If set to ``true``, project is enabled. If set to
+    ``false``, project is disabled.
+  in: body
+  required: false
+  type: boolean
+project_id_response_body:
+  description: |
+    The ID for the project.
+  in: body
+  required: true
+  type: string
+project_name_request_body:
+  description: |
+    The name of the project, which must be unique within the
+    owning domain. A project can have the same name as its domain.
+  in: body
+  required: true
+  type: string
+project_name_response_body:
+  description: |
+    The name of the project.
+  in: body
+  required: true
+  type: string
+project_name_update_request_body:
+  description: |
+    The name of the project, which must be unique within the
+    owning domain. A project can have the same name as its domain.
+  in: body
+  required: false
+  type: string
+project_parent_id_request_body:
+  description: |
+    The ID of the parent of the project.
+
+    If specified on project creation, this places the project within a
+    hierarchy and implicitly defines the owning domain, which will be the
+    same domain as the parent specified. If ``parent_id`` is
+    not specified and ``is_domain`` is ``false``, then the project will use its
+    owning domain as its parent. If ``is_domain`` is ``true`` (i.e. the project
+    is acting as a domain), then ``parent_id`` must not specified (or if it is,
+    it must be ``null``) since domains have no parents.
+
+    ``parent_id`` is immutable, and can't be updated after the project is
+    created - hence a project cannot be moved within the hierarchy.
+  in: body
+  required: false
+  type: string
+  min_version: 3.4
+project_parent_id_response_body:
+  description: |
+    The ID of the parent for the project.
+  in: body
+  required: true
+  type: string
+  min_version: 3.4
 projects:
   description: |
-    A ``projects`` object.
+    A list of ``project`` objects, each containing:
   in: body
   required: true
   type: array

api-ref/source/v3/projects.inc

@@ -42,25 +42,26 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - domain_id: domain_id
+   - domain_id: domain_id_query
-   - parent_id: parent_id
+   - enabled: project_enabled_query
-   - name: name
+   - name: project_name_query
-   - enabled: enabled
+   - parent_id: parent_id_query
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - is_domain: is_domain
+   - links: link_collection
-   - description: description
-   - links: links
-   - enabled: enabled
-   - domain_id: domain_id
-   - parent_id: parent_id
-   - id: id
    - projects: projects
-   - name: name
+   - is_domain: is_domain_response_body
+   - description: project_description_response_body
+   - domain_id: project_domain_id_response_body
+   - enabled: project_enabled_response_body
+   - id: project_id_response_body
+   - links: link_response_body
+   - name: project_name_response_body
+   - parent_id: project_parent_id_response_body
 
 Response Example
 ----------------
@@ -74,13 +75,7 @@ Create project
 
 .. rest_method::  POST /v3/projects
 
-Creates a project.
+Creates a project, including a project acting as a domain.
-
-Projects that are acting as a domain (i.e. with ``parent_id`` set to
-``true``) must also be specified with no parent (i.e. if ``parent_id`` is
-included it must be null). Issuing a create project request for a project
-acting as a domain with a ``parent_id`` that is not null will fail with a
-``Bad Request (400)`` response code being returned.
 
 Normal response codes: 201
 Error response codes: 413,415,405,404,403,401,400,503,409
@@ -90,34 +85,37 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - is_domain: is_domain
-   - description: description
-   - enabled: enabled
    - project: project
-   - parent_id: parent_id
+   - is_domain: is_domain_request_body
-   - domain_id: domain_id
+   - description: project_description_request_body
-   - name: name
+   - domain_id: project_domain_id_request_body
+   - enabled: project_enabled_request_body
+   - name: project_name_request_body
+   - parent_id: project_parent_id_request_body
 
-Request Example
+Request Examples
----------------
+----------------
 
 .. literalinclude:: ./samples/admin/project-create-request.json
    :language: javascript
 
+.. literalinclude:: ./samples/admin/project-create-domain-request.json
+   :language: javascript
+
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - is_domain: is_domain
-   - description: description
-   - links: links
-   - enabled: enabled
-   - domain_id: domain_id
    - project: project
-   - parent_id: parent_id
+   - is_domain: is_domain_response_body
-   - id: id
+   - description: project_description_response_body
-   - name: name
+   - domain_id: project_domain_id_response_body
+   - enabled: project_enabled_response_body
+   - id: project_id_response_body
+   - links: link_response_body
+   - name: project_name_response_body
+   - parent_id: project_parent_id_response_body
 
 
 Show project details
@@ -135,22 +133,22 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - project_id: project_id
+   - project_id: project_id_path
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - is_domain: is_domain
-   - description: description
-   - links: links
-   - enabled: enabled
-   - domain_id: domain_id
    - project: project
-   - parent_id: parent_id
+   - is_domain: is_domain_response_body
-   - id: id
+   - description: project_description_response_body
-   - name: name
+   - domain_id: project_domain_id_response_body
+   - enabled: project_enabled_response_body
+   - id: project_id_response_body
+   - links: link_response_body
+   - name: project_name_response_body
+   - parent_id: project_parent_id_response_body
 
 Response Example
 ----------------
@@ -174,13 +172,12 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - description: description
+   - project_id: project_id_path
-   - enabled: enabled
    - project: project
-   - parent_id: parent_id
+   - description: project_description_request_body
-   - domain_id: domain_id
+   - domain_id: project_domain_id_update_request_body
-   - name: name
+   - enabled: project_enabled_update_request_body
-   - project_id: project_id
+   - name: project_name_update_request_body
 
 Request Example
 ---------------
@@ -193,15 +190,15 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - is_domain: is_domain
-   - description: description
-   - links: links
-   - enabled: enabled
-   - domain_id: domain_id
    - project: project
-   - parent_id: parent_id
+   - is_domain: is_domain_response_body
-   - id: id
+   - description: project_description_response_body
-   - name: name
+   - domain_id: project_domain_id_response_body
+   - enabled: project_enabled_response_body
+   - id: project_id_response_body
+   - name: project_name_response_body
+   - links: link_response_body
+   - parent_id: project_parent_id_response_body
 
 Response Example
 ----------------
@@ -225,7 +222,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - project_id: project_id
+   - project_id: project_id_path
 
 
 Enable or disable project and its subtree
@@ -233,7 +230,7 @@ Enable or disable project and its subtree
 
 .. rest_method::  PATCH /v3/projects/{project_id}/cascade
 
-(Since Identity API v3.6) Enables or disables a project and its entire subtree.
+(Since Identity API v3.7) Enables or disables a project and its entire subtree.
 
 A project subtree includes all projects beneath the parent project
 in the hierarchy.
@@ -254,9 +251,9 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
+   - project_id: project_id_path
    - project: project
-   - enabled: enabled
+   - enabled: project_enabled_cascade_request_body
-   - project_id: project_id
 
 Request Example
 ---------------
@@ -269,15 +266,15 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - is_domain: is_domain
-   - description: description
-   - links: links
-   - enabled: enabled
-   - domain_id: domain_id
    - project: project
-   - parent_id: parent_id
+   - is_domain: is_domain_response_body
-   - id: id
+   - description: project_description_response_body
-   - name: name
+   - domain_id: project_domain_id_response_body
+   - enabled: project_enabled_response_body
+   - id: project_id_response_body
+   - name: project_name_response_body
+   - links: link_response_body
+   - parent_id: project_parent_id_response_body
 
 Response Example
 ----------------
@@ -291,7 +288,7 @@ Delete project subtree
 
 .. rest_method::  DELETE /v3/projects/{project_id}/cascade
 
-(Since Identity API v3.6) Deletes a project and its entire subtree.
+(Since Identity API v3.7) Deletes a project and its entire subtree.
 
 A project subtree includes all projects beneath the parent project
 in the hierarchy. You must disable all the projects in the subtree
@@ -305,4 +302,4 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - project_id: project_id
+   - project_id: project_id_path

api-ref/source/v3/samples/admin/project-create-domain-request.json

@@ -0,0 +1,8 @@
+{
+    "project": {
+        "description": "My new domain",
+        "enabled": true,
+        "is_domain": true,
+        "name": "myNewDomain"
+    }
+}

api-ref/source/v3/samples/admin/project-create-request.json

@@ -3,7 +3,7 @@
         "description": "My new project",
         "domain_id": "default",
         "enabled": true,
-        "is_domain": true,
+        "is_domain": false,
         "name": "myNewProject"
     }
 }

api-ref/source/v3/samples/admin/project-create-response.json

@@ -1,14 +1,14 @@
 {
     "project": {
-        "is_domain": true,
         "description": "My new project",
+        "domain_id": "default",
+        "enabled": true,
+        "id": "93ebbcc35335488b96ff9cd7d18cbb2e",
+        "is_domain": false,
         "links": {
             "self": "http://example.com/identity/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e"
         },
-        "enabled": true,
+        "name": "myNewProject",
-        "id": "93ebbcc35335488b96ff9cd7d18cbb2e",
+        "parent_id": "default"
-        "parent_id": null,
-        "domain_id": "default",
-        "name": "myNewProject"
     }
 }

api-ref/source/v3/samples/admin/project-show-response.json

@@ -9,6 +9,6 @@
             "self": "http://example.com/identity/v3/projects/0c4e939acacf4376bdcd1129f1a054ad"
         },
         "name": "admin",
-        "parent_id": null
+        "parent_id": "default"
     }
 }

api-ref/source/v3/samples/admin/project-update-request.json

@@ -1,8 +1,6 @@
 {
     "project": {
         "description": "My updated project",
-        "domain_id": "default",
-        "enabled": true,
         "name": "myUpdatedProject"
     }
 }

api-ref/source/v3/samples/admin/project-update-response.json

@@ -1,17 +1,14 @@
 {
     "project": {
-        "is_domain": true,
         "description": "My updated project",
+        "domain_id": null,
         "links": {
             "self": "http://example.com/identity/v3/projects/93ebbcc35335488b96ff9cd7d18cbb2e"
         },
-        "extra": {
-            "is_domain": true
-        },
         "enabled": true,
         "id": "93ebbcc35335488b96ff9cd7d18cbb2e",
-        "parent_id": null,
+        "is_domain": true,
-        "domain_id": "default",
         "name": "myUpdatedProject"
+        "parent_id": null,
     }
 }