diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 3846132714..39ac05acd3 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/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 - acts as a domain. Set to ``true`` to define this project as both - a project and domain. As a domain, the project provides a name - space in which you can create users, groups, and other projects. - Set to ``false`` to define this project as a regular project that - contains only resources. Default is ``false``. You cannot update + Indicates whether the project also acts as a domain. If set to ``true``, + this project acts as both a project and domain. As a domain, the project + provides a name space in which you can create users, groups, and other + projects. If set to ``false``, this project behaves as a regular project + that 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 - acts as a domain. If set to ``true``, this project acts as both a - project and domain. As a domain, the project provides a name space - in which you can create users, groups, and other projects. - Otherwise, this field does not appear in the response and this - project behaves as a regular project that contains only resources. + Indicates whether the project also acts as a domain. If set to ``true``, + this project acts as both a project and domain. As a domain, the project + provides a name space in which you can create users, groups, and other + projects. If set to ``false``, this 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. - in: body - required: true - type: string -project_id_2: - description: | - The UUID for the associated project. + The description of the 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 diff --git a/api-ref/source/v3/projects.inc b/api-ref/source/v3/projects.inc index 9a31af2d58..4703316df8 100644 --- a/api-ref/source/v3/projects.inc +++ b/api-ref/source/v3/projects.inc @@ -42,25 +42,26 @@ Request .. rest_parameters:: parameters.yaml - - domain_id: domain_id - - parent_id: parent_id - - name: name - - enabled: enabled + - domain_id: domain_id_query + - enabled: project_enabled_query + - name: project_name_query + - parent_id: parent_id_query Response Parameters ------------------- .. rest_parameters:: parameters.yaml - - is_domain: is_domain - - description: description - - links: links - - enabled: enabled - - domain_id: domain_id - - parent_id: parent_id - - id: id + - links: link_collection - 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. - -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. +Creates a project, including a project acting as a domain. 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 - - domain_id: domain_id - - name: name + - is_domain: is_domain_request_body + - description: project_description_request_body + - 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 - - id: id - - 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 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 - - id: id - - 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 ---------------- @@ -174,13 +172,12 @@ Request .. rest_parameters:: parameters.yaml - - description: description - - enabled: enabled + - project_id: project_id_path - project: project - - parent_id: parent_id - - domain_id: domain_id - - name: name - - project_id: project_id + - description: project_description_request_body + - domain_id: project_domain_id_update_request_body + - enabled: project_enabled_update_request_body + - 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 - - id: id - - 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 + - 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 - - project_id: project_id + - enabled: project_enabled_cascade_request_body 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 - - id: id - - 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 + - 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 diff --git a/api-ref/source/v3/samples/admin/project-create-domain-request.json b/api-ref/source/v3/samples/admin/project-create-domain-request.json new file mode 100644 index 0000000000..2a2a201174 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/v3/samples/admin/project-create-request.json b/api-ref/source/v3/samples/admin/project-create-request.json index 76c9411556..409dae86ae 100644 --- a/api-ref/source/v3/samples/admin/project-create-request.json +++ b/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" } } diff --git a/api-ref/source/v3/samples/admin/project-create-response.json b/api-ref/source/v3/samples/admin/project-create-response.json index 661cc44831..42c41d6ff3 100644 --- a/api-ref/source/v3/samples/admin/project-create-response.json +++ b/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, - "id": "93ebbcc35335488b96ff9cd7d18cbb2e", - "parent_id": null, - "domain_id": "default", - "name": "myNewProject" + "name": "myNewProject", + "parent_id": "default" } } diff --git a/api-ref/source/v3/samples/admin/project-show-response.json b/api-ref/source/v3/samples/admin/project-show-response.json index 58894f1d5b..573bf16d6f 100644 --- a/api-ref/source/v3/samples/admin/project-show-response.json +++ b/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" } } diff --git a/api-ref/source/v3/samples/admin/project-update-request.json b/api-ref/source/v3/samples/admin/project-update-request.json index 6cc0bdb34b..dd26d8f9dc 100644 --- a/api-ref/source/v3/samples/admin/project-update-request.json +++ b/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" } } diff --git a/api-ref/source/v3/samples/admin/project-update-response.json b/api-ref/source/v3/samples/admin/project-update-response.json index a61a3309fd..3f08b03258 100644 --- a/api-ref/source/v3/samples/admin/project-update-response.json +++ b/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, - "domain_id": "default", + "is_domain": true, "name": "myUpdatedProject" + "parent_id": null, } }