From c41555d8eea2a32e25472570fbf0380a001adbc4 Mon Sep 17 00:00:00 2001 From: Graham Hayes Date: Mon, 16 May 2016 17:32:42 +0100 Subject: [PATCH] Add Zone Transfer Request + Accept API-Ref docs Change-Id: Ibd10ded10b8e304f3548c2f3cc60ab5c64b600b8 --- ...-api-v2-zone-ownership-transfer-accept.inc | 94 +++++++ ...api-v2-zone-ownership-transfer-request.inc | 249 ++++++++++++++++++ api-ref/source/index.rst | 2 + api-ref/source/parameters.yaml | 103 +++++++- .../create-zone-transfer-accept-request.json | 4 + .../create-zone-transfer-accept-response.json | 8 + .../create-zone-transfer-request-request.json | 3 + ...create-zone-transfer-request-response.json | 15 ++ .../list-zone-transfer-request-response.json | 32 +++ .../show-zone-transfer-request-response.json | 10 + .../update-zone-transfer-request-request.json | 4 + ...update-zone-transfer-request-response.json | 11 + 12 files changed, 533 insertions(+), 2 deletions(-) create mode 100644 api-ref/source/dns-api-v2-zone-ownership-transfer-accept.inc create mode 100644 api-ref/source/dns-api-v2-zone-ownership-transfer-request.inc create mode 100644 api-ref/source/samples/zones/create-zone-transfer-accept-request.json create mode 100644 api-ref/source/samples/zones/create-zone-transfer-accept-response.json create mode 100644 api-ref/source/samples/zones/create-zone-transfer-request-request.json create mode 100644 api-ref/source/samples/zones/create-zone-transfer-request-response.json create mode 100644 api-ref/source/samples/zones/list-zone-transfer-request-response.json create mode 100644 api-ref/source/samples/zones/show-zone-transfer-request-response.json create mode 100644 api-ref/source/samples/zones/update-zone-transfer-request-request.json create mode 100644 api-ref/source/samples/zones/update-zone-transfer-request-response.json diff --git a/api-ref/source/dns-api-v2-zone-ownership-transfer-accept.inc b/api-ref/source/dns-api-v2-zone-ownership-transfer-accept.inc new file mode 100644 index 000000000..f16ff6cac --- /dev/null +++ b/api-ref/source/dns-api-v2-zone-ownership-transfer-accept.inc @@ -0,0 +1,94 @@ +================================== +Zone Ownership Transfers - Accepts +================================== + +Designate allows users to transer ownership of a zone between projects. + +For the final step, the receiving project has to accept the new zone, using +the ``transfer_accepts`` API + + +Create Zone Transfer Accept +============================ + +.. rest_method:: POST /v2/zones/{zone_id}/tasks/transfer_accepts + +This accepts an offer of a ownership transfer + + +Normal response codes: 200 +Error response codes:405,404,403,401,400,503, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - x-auth-token: x-auth-token + - x-auth-all-projects: x-auth-all-projects + - x-auth-sudo-project-id: x-auth-sudo-project-id + - key: zone_transfer_request_key + - zone_id: zone_transfer_request_id + + +Request Example +---------------- + +.. literalinclude:: samples/zones/create-zone-transfer-accept-request.json + :language: javascript + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - x-openstack-request-id: x-openstack-request-id + - id: zone_transfer_accept_id + - status: zone_transfer_request_status + - links: links + +Response Example +---------------- + +.. literalinclude:: samples/zones/create-zone-transfer-accept-response.json + :language: javascript + + +Get Zone Transfer Accept +======================== + +.. rest_method:: GET /v2/zones/tasks/transfer_requests/{zone_transfer_accept_id} + + +Normal response codes: 200 +Error response codes:405,404,403,401,400,503, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - x-auth-token: x-auth-token + - x-auth-all-projects: x-auth-all-projects + - x-auth-sudo-project-id: x-auth-sudo-project-id + - zone_transfer_accept_id: path_zone_transfer_accept_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - x-openstack-request-id: x-openstack-request-id + - id: zone_transfer_accept_id + - status: zone_transfer_request_status + - links: links + +Response Example +---------------- + +.. literalinclude:: samples/zones/create-zone-transfer-accept-response.json + :language: javascript diff --git a/api-ref/source/dns-api-v2-zone-ownership-transfer-request.inc b/api-ref/source/dns-api-v2-zone-ownership-transfer-request.inc new file mode 100644 index 000000000..c6d1e98f2 --- /dev/null +++ b/api-ref/source/dns-api-v2-zone-ownership-transfer-request.inc @@ -0,0 +1,249 @@ +=================================== +Zone Ownership Transfers - Requests +=================================== + +Designate allows users to transer ownership of a zone between projects. + +The traditional route is to create a ``zone_transfer_request``, communicate +the key and ID out of band to the intended owner, and they create a +``zone_transfer_accept`` using this information, which will move the +ownership of the zone that project. + + +Create Zone Transfer Request +============================ + +.. rest_method:: POST /v2/zones/{zone_id}/tasks/transfer_requests + +This creates an offer to transfer the zone to a different project. +The request can be scoped to single project if the ``project_id`` parameter is +supplied. + +.. note:: This POST can have no body. + + +Normal response codes: 200 +Error response codes:405,404,403,401,400,503, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - x-auth-token: x-auth-token + - x-auth-all-projects: x-auth-all-projects + - x-auth-sudo-project-id: x-auth-sudo-project-id + - zone_id: path_zone_id + - target_project_id: zone_transfer_request_target_project_id + - description: description + +Request Example +---------------- + +.. literalinclude:: samples/zones/create-zone-transfer-request-request.json + :language: javascript + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - x-openstack-request-id: x-openstack-request-id + - id: zone_transfer_request_id + - project_id: project_id + - description: description + - status: zone_transfer_request_status + - zone_id: zone_transfer_request_zone_id + - zone_name: zone_transfer_request_zone_name + - key: zone_transfer_request_key + - target_project_id: zone_transfer_request_target_project_id + - created_at: created_at + - updated_at: updated_at + - version: version + +Response Example +---------------- + +.. literalinclude:: samples/zones/create-zone-transfer-request-response.json + :language: javascript + + +List Zone Transfer Requests +=========================== + +.. rest_method:: GET /v2/zones/tasks/transfer_requests + +This will list all your outgoing requests, and any incoming requests that +have been scoped to your project. + +Normal response codes: 200 +Error response codes:405,404,403,401,400,503, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - x-auth-token: x-auth-token + - x-auth-all-projects: x-auth-all-projects + - x-auth-sudo-project-id: x-auth-sudo-project-id + - status: zone_transfer_request_status_filter + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - x-openstack-request-id: x-openstack-request-id + - id: zone_transfer_request_id + - project_id: project_id + - description: description + - status: zone_transfer_request_status + - zone_id: zone_transfer_request_zone_id + - zone_name: zone_transfer_request_zone_name + - key: zone_transfer_request_key + - target_project_id: zone_transfer_request_target_project_id + - created_at: created_at + - updated_at: updated_at + - version: version + +Response Example +---------------- + +.. literalinclude:: samples/zones/list-zone-transfer-request-response.json + :language: javascript + + + +Show a Zone Transfer Request +============================ + +.. rest_method:: GET /v2/zones/tasks/transfer_requests/{zone_transfer_request_id} + + +Normal response codes: 200 +Error response codes:405,404,403,401,400,503, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - x-auth-token: x-auth-token + - x-auth-all-projects: x-auth-all-projects + - x-auth-sudo-project-id: x-auth-sudo-project-id + - zone_transfer_request_id: path_zone_transfer_request_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - x-openstack-request-id: x-openstack-request-id + - id: zone_transfer_request_id + - project_id: project_id + - description: description + - status: zone_transfer_request_status + - zone_id: zone_transfer_request_zone_id + - zone_name: zone_transfer_request_zone_name + - key: zone_transfer_request_key + - target_project_id: zone_transfer_request_target_project_id + - created_at: created_at + - updated_at: updated_at + - version: version + +Response Example +---------------- + +.. literalinclude:: samples/zones/show-zone-transfer-request-response.json + :language: javascript + + +Update a Zone Transfer Request +============================== + +.. rest_method:: PATCH /v2/zones/tasks/transfer_requests/{zone_transfer_request_id} + + +Normal response codes: 200 +Error response codes:405,404,403,401,400,503, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - x-auth-token: x-auth-token + - x-auth-all-projects: x-auth-all-projects + - x-auth-sudo-project-id: x-auth-sudo-project-id + - zone_transfer_request_id: path_zone_transfer_request_id + - target_project_id: zone_transfer_request_target_project_id + - description: description + +Request Example +---------------- + +.. literalinclude:: samples/zones/update-zone-transfer-request-request.json + :language: javascript + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - x-openstack-request-id: x-openstack-request-id + - id: zone_transfer_request_id + - project_id: project_id + - description: description + - status: zone_transfer_request_status + - zone_id: zone_transfer_request_zone_id + - zone_name: zone_transfer_request_zone_name + - key: zone_transfer_request_key + - target_project_id: zone_transfer_request_target_project_id + - created_at: created_at + - updated_at: updated_at + - version: version + +Response Example +---------------- + +.. literalinclude:: samples/zones/update-zone-transfer-request-response.json + :language: javascript + + +Delete a Zone Transfer Request +============================== + +.. rest_method:: DELETE /v2/zones/tasks/transfer_requests/{zone_transfer_request_id} + + +Normal response codes: 204 +Error response codes:405,404,403,401,400,503, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - x-auth-token: x-auth-token + - x-auth-all-projects: x-auth-all-projects + - x-auth-sudo-project-id: x-auth-sudo-project-id + - zone_transfer_request_id: path_zone_transfer_request_id + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - x-openstack-request-id: x-openstack-request-id + diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 7153ba71f..0ab6cb058 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -10,4 +10,6 @@ .. include:: dns-api-v2-zone-import.inc .. include:: dns-api-v2-zone-export.inc .. include:: dns-api-v2-zone-tasks.inc +.. include:: dns-api-v2-zone-ownership-transfer-request.inc +.. include:: dns-api-v2-zone-ownership-transfer-accept.inc .. include:: dns-api-v2-recordset.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index f4a920331..a6971747a 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -148,7 +148,7 @@ updated_at: description: | Date / Time when resource last updated in: body - required: true + required: false type: datestamp status: @@ -609,7 +609,7 @@ zone_export_status: Current status of the zone export in: body required: true - type: uuid + type: string zone_export_message: description: | @@ -639,6 +639,105 @@ zone_export_location: type: string + +################################# +# Zone Transfer Variables # +################################# + + +# Header Variables +################### + +# Path Variables +################# + +path_zone_transfer_request_id: + description: | + ID for this zone transfer request + in: path + required: true + type: uuid + +path_zone_accept_request_id: + description: | + ID for this zone transfer accept + in: path + required: true + type: uuid + +# Query Variables +################## + +# Filters +# 'status' + +zone_transfer_request_status_filter: + description: | + Filter results to only show ``zone_transfer_requests`` that have a ``status`` matching the filter + in: query + required: false + type: string + +# Body Variables +################# +zone_transfer_request_id: + description: | + ID for this zone transfer request + in: path + required: true + type: uuid + +zone_transfer_accept_id: + description: | + ID for this zone transfer accept + in: path + required: true + type: uuid + +zone_transfer_request_target_project_id: + description: > + A project ID that the request will be limited to. + No other project will be allowed to accept this request. + in: body + required: false + type: string + +zone_transfer_request_status: + description: | + Current status of the zone transfer request + in: body + required: true + type: string + +zone_transfer_accept_status: + description: | + Current status of the zone transfer request + in: body + required: true + type: string + +zone_transfer_request_key: + description: > + Key that is used as part of the zone transfer accept process. This is only + shown to the creator, and must be communicated out of band. + in: body + required: true + type: string + +zone_transfer_request_zone_id: + description: | + ID for the zone that is being exported + in: body + required: true + type: uuid + +zone_transfer_request_zone_name: + description: | + the name of the zone that is being exported + in: body + required: true + type: string + ############################# # Variables # ############################# diff --git a/api-ref/source/samples/zones/create-zone-transfer-accept-request.json b/api-ref/source/samples/zones/create-zone-transfer-accept-request.json new file mode 100644 index 000000000..d9977b077 --- /dev/null +++ b/api-ref/source/samples/zones/create-zone-transfer-accept-request.json @@ -0,0 +1,4 @@ +{ + "key":"9Z2R50Y0", + "zone_transfer_request_id":"f2ad17b5-807a-423f-a991-e06236c247be" +} diff --git a/api-ref/source/samples/zones/create-zone-transfer-accept-response.json b/api-ref/source/samples/zones/create-zone-transfer-accept-response.json new file mode 100644 index 000000000..24e97021f --- /dev/null +++ b/api-ref/source/samples/zones/create-zone-transfer-accept-response.json @@ -0,0 +1,8 @@ +{ + "id": "581891d5-99f5-49e1-86c3-eec0f44d66fd", + "links": { + "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_accepts/581891d5-99f5-49e1-86c3-eec0f44d66fd", + "zone": "http://127.0.0.1:9001/v2/zones/6b78734a-aef1-45cd-9708-8eb3c2d26ff8" + }, + "status": "COMPLETE" +} diff --git a/api-ref/source/samples/zones/create-zone-transfer-request-request.json b/api-ref/source/samples/zones/create-zone-transfer-request-request.json new file mode 100644 index 000000000..670e1c8f3 --- /dev/null +++ b/api-ref/source/samples/zones/create-zone-transfer-request-request.json @@ -0,0 +1,3 @@ +{ + "project_id": "1" +} diff --git a/api-ref/source/samples/zones/create-zone-transfer-request-response.json b/api-ref/source/samples/zones/create-zone-transfer-request-response.json new file mode 100644 index 000000000..90d6a3502 --- /dev/null +++ b/api-ref/source/samples/zones/create-zone-transfer-request-response.json @@ -0,0 +1,15 @@ +{ + "created_at": "2014-07-17T20:34:40.882579", + "description": null, + "id": "f2ad17b5-807a-423f-a991-e06236c247be", + "key": "9Z2R50Y0", + "project_id": "1", + "status": "ACTIVE", + "target_project_id": "123456", + "updated_at": null, + "zone_id": "6b78734a-aef1-45cd-9708-8eb3c2d26ff8", + "zone_name": "qa.dev.example.com.", + "links": { + "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/f2ad17b5-807a-423f-a991-e06236c247be" + } +} diff --git a/api-ref/source/samples/zones/list-zone-transfer-request-response.json b/api-ref/source/samples/zones/list-zone-transfer-request-response.json new file mode 100644 index 000000000..2f74d0519 --- /dev/null +++ b/api-ref/source/samples/zones/list-zone-transfer-request-response.json @@ -0,0 +1,32 @@ +{ + "transfer_requests": [ + { + "created_at": "2014-07-17T20:34:40.882579", + "description": "This was created by the requesting project", + "id": "f2ad17b5-807a-423f-a991-e06236c247be", + "key": "9Z2R50Y0", + "project_id": "1", + "status": "ACTIVE", + "target_project_id": "123456", + "updated_at": null, + "zone_id": "6b78734a-aef1-45cd-9708-8eb3c2d26ff8", + "zone_name": "qa.dev.example.com.", + "links": { + "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/f2ad17b5-807a-423f-a991-e06236c247be" + } + }, + { + "description": "This is scoped to the requesting project", + "id": "efd2d720-b0c4-43d4-99f7-d9b53e08860d", + "zone_id": "2c4d5e37-f823-4bee-9859-031cb44f80e7", + "zone_name": "subdomain.example.com.", + "status": "ACTIVE", + "links": { + "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/efd2d720-b0c4-43d4-99f7-d9b53e08860d" + } + } + ], + "links": { + "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests" + } +} diff --git a/api-ref/source/samples/zones/show-zone-transfer-request-response.json b/api-ref/source/samples/zones/show-zone-transfer-request-response.json new file mode 100644 index 000000000..c81b9941e --- /dev/null +++ b/api-ref/source/samples/zones/show-zone-transfer-request-response.json @@ -0,0 +1,10 @@ +{ + "description": "This is scoped to the requesting project", + "id": "efd2d720-b0c4-43d4-99f7-d9b53e08860d", + "zone_id": "2c4d5e37-f823-4bee-9859-031cb44f80e7", + "zone_name": "subdomain.example.com.", + "status": "ACTIVE", + "links": { + "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/efd2d720-b0c4-43d4-99f7-d9b53e08860d" + } +} diff --git a/api-ref/source/samples/zones/update-zone-transfer-request-request.json b/api-ref/source/samples/zones/update-zone-transfer-request-request.json new file mode 100644 index 000000000..2c1bb44e9 --- /dev/null +++ b/api-ref/source/samples/zones/update-zone-transfer-request-request.json @@ -0,0 +1,4 @@ +{ + "description": "This is scoped to the new project", + "target_project_id": "987654", +} diff --git a/api-ref/source/samples/zones/update-zone-transfer-request-response.json b/api-ref/source/samples/zones/update-zone-transfer-request-response.json new file mode 100644 index 000000000..b564cc79c --- /dev/null +++ b/api-ref/source/samples/zones/update-zone-transfer-request-response.json @@ -0,0 +1,11 @@ +{ + "description": "This is scoped to the new project", + "target_project_id": "987654", + "id": "efd2d720-b0c4-43d4-99f7-d9b53e08860d", + "zone_id": "2c4d5e37-f823-4bee-9859-031cb44f80e7", + "zone_name": "subdomain.example.com.", + "status": "ACTIVE", + "links": { + "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/efd2d720-b0c4-43d4-99f7-d9b53e08860d" + } +}