From 1c6e396e2d87ba97150c8e93291e81bcd1ca3f0b Mon Sep 17 00:00:00 2001 From: Bryan Strassner Date: Tue, 29 Aug 2017 09:55:42 -0500 Subject: [PATCH] Update to make the commitconfigdocs API be sync. Removed the commit_configdocs action. Change-Id: I30e908d5afb6e70cb487a7db089f45a08ef2f848 --- docs/API.md | 60 ++++++++++++++++++++++++++----------- docs/API_action_commands.md | 13 -------- 2 files changed, 42 insertions(+), 31 deletions(-) diff --git a/docs/API.md b/docs/API.md index 434d9dfb..4f5f41f2 100644 --- a/docs/API.md +++ b/docs/API.md @@ -41,14 +41,15 @@ Deckhand #### POST Ingests a collection of documents. Synchronous. POSTing an empty body -indicates that the specified collection should be deleted if the Shipyard -Buffer is committed. +indicates that the specified collection should be deleted when the Shipyard +Buffer is committed. If a POST to the commitconfigdocs is in progress, this +POST should be rejected with a 409 error. ##### Query Parameters * bufferMode=append|replace|**rejectOnContents** Indicates how the existing Shipyard Buffer should be handled. By default, Shipyard will reject the POST if contents already exist in the Shipyard -Buffer. +Buffer. * append: Add the collection to the Shipyard Buffer, only if that collection doesn't already exist in the Shipyard Buffer. If the collection is already present, the request will be rejected and a 409 Conflict will be @@ -63,7 +64,7 @@ Response message includes: to retrieve the configDocs * 409 Conflict - * If a commit_configdocs action is in progress. + * If a commitconfigdocs POST is in progress. * If any collections exist in the Shipyard Buffer unless bufferMode=replace or bufferMode=append. * If bufferMode=append, and the collection being posted is already in the @@ -103,27 +104,50 @@ Return the documents for the version specified - buffer by default. If documents can be retrieved. --- -### /v1.0/validations -Represents the validation messages for the documents in deckhand +### /v1.0/commitconfigdocs +A RPC style command to trigger a commit of the configuration documents from the +Shipyard Buffer to the Committed Documents. This resource will support POST +only. #### Payload Structure -The list of validations -``` -[ - { TBD } -] -``` +The response will be the list of validations from all downstream systems that +perform validation during the commit process. The structure will match the +error response object described in the [UCP API conventions](https://github.com/att-comdev/ucp-integration/blob/master/docs/api-conventions.md) +and will be an aggregation of each UCP component's responses. -#### GET -Returns the validations +#### POST +Performs the commit of the Shipyard Buffer to the Committed Documents. +Synchronous. This invokes each of the UCP components to examine the Shipyard +Buffer version of the configuration documents and aggregate the responses. +While performing this commit, further POSTing of configdocs, or other commits +may not be invoked (Shipyard will block those requests with a 409 response). +If there are any failures to validate, the Shipyard Buffer and Commited +Documents will remain unchanged. If successful, the Shipyard Buffer will be +cleared, and the Committed documents will be updated. + +**Note**: if there are unhandled runtime errors during the commitconfigdocs POST, +a deadlock situation may be possible. Future enhancements may improve this +handling. ##### Query Parameters -* version=committed|**buffer** -returns the validations if any associated with the version specified. +* force=true|**false** +By default, false, if there are validation failures the POST will fail with +a 400 response. With force=true, allows for the commit to succeed (with a 200 +response) even if there are validation failures from downstream components. The +aggregate response of validation failures will be returned in this case, but +the invalid documents will still be moved from the Shipyard Buffer to the +Committed Documents. ##### Responses * 200 OK -If the validations can be retrieved. - +If the validations are successful. Returns an "empty" structure as as response +indicating no errors. A 200 may also be returned if there are validation +failures, but the force=true query parameter was specified. In this case, the +response will contain the list of validations. +* 400 Bad Request +If the validations fail. Returns a populated response structure containing +the aggregation of the failed validations. +* 409 Conflict +If the there is a POST to commitconfigdocs in progress. --- ## Action API >The Shipyard Action API is a resource that allows for creation, control and diff --git a/docs/API_action_commands.md b/docs/API_action_commands.md index c5e8b661..64a2410e 100644 --- a/docs/API_action_commands.md +++ b/docs/API_action_commands.md @@ -35,19 +35,6 @@ configuration documents. Steps: (same as deploy_site) Using parameters to indicate which server(s), triggers a redeployment of server to the last known good design and secrets -* commit_configdocs -This signals to shipyard that the documents in the shipyard buffer should be -committed to the site as design. Steps: - 1) Blocks Shipyard from accepting any documents for the duration of the - commit_configdocs action to prevent unexpected behavior of the buffer in the - case of validation failures. - 2) Triggers validations by the various UCP components against the documents - in the Shipyard Buffer. - * If all validations pass, tags the revision in Deckhand as a committed - version. This will effecively "empty" the Shipyard Buffer. - * If validations fail, the Shipyard Buffer will remain in the state it - was before the commit_configdocs started. - --- ## Future actions These actions are anticipated for development