Vijay-1 commented on a change in pull request #2029: Implements https://github.com/apache/incubator-trafficcontrol/issues/… URL: https://github.com/apache/incubator-trafficcontrol/pull/2029#discussion_r178110405
########## File path: docs/source/development/traffic_ops_api/v12/cachegroup_fallbacks.rst ########## @@ -0,0 +1,266 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + +.. _to-api-v12-cachegroupfallbacks: + +Cache Group Fallback +==================== + +.. _to-api-v12-cachegroupfallbacks-route: + +/api/1.2/cachegroups/fallbacks +++++++++++++++++++++++++++++++ + +**GET /api/1.2/cachegroups/:id/fallbacks** + + Retrieves the fallback list assigned to the cache group. + + Authentication Required: Yes + + Role(s) Required: None + + **Request Route Parameters** + + +------+----------+---------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+===========================================================================+ + | id | yes | The id of the cache group whose backup configurations has to be retrieved | + +------+----------+---------------------------------------------------------------------------+ + + **Response Properties** + + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===================================+========+==========================================================================+ + | | array | parameters array | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``>name`` | string | Fallback cache group name | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``>order`` | int | Ordering list in the list of backups | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "order":10, + "name":"GROUP2" + } + ] + } + +| + +**POST /api/1.2/cachegroups/:id/fallbacks** + + Creates fallback list for the cache group. After a succesful POST, Subsequent requests will be failed. + + Authentication Required: Yes + + Role(s) Required: admin or oper + + **Request Route Parameters** + + +------+----------+-----------------------------------------------------------------------------+ + | Name | Required | Description | + +======+==========+=============================================================================+ + | id | yes | The id of the cache group for which backup configurations has to be created | + +------+----------+-----------------------------------------------------------------------------+ + + **Request Parameters** + The request parameters should be in array format. + + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===================================+========+==========================================================================+ + | | array | parameters array | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``>name`` | string | Fallback cache group name | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``>order`` | int | Ordering list in the list of backups | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + + **Request Example** :: + + [ + { + "name": "GROUP2", + "order": 10 + } + ] + + **Response Properties** + + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | Parameter | Type | Description | + +===================================+========+==========================================================================+ + | | array | parameters array | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``>name`` | string | Fallback cache group name | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``>order`` | int | Ordering list in the list of backups | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``alerts`` | array | A collection of alert messages. | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + | ``>text`` | string | Alert message. | + +-----------------------------------+--------+--------------------------------------------------------------------------+ + + + **Response Example** :: + + { + "alerts": [ + { + "level":"success", + "text":"Backup configuration for 1 successful." + } + ], + "response": [ + { + "order":10, + "name":"GROUP2" + } + ] + } + +| + +**PUT /api/1.2/cachegroups/:id/fallbacks** + + Updates an already existing fallback list for the cache group (Existing fallback list will be deleted). Review comment: @mitchell852 This has be discussed earlier and here is the summary of how it was thought about to start : <snip> 1. POST: receive a full list of ordered backups and create the fallback list. If the fallback list already exists, render a failure. 2. PUT: receive a full list of ordered backups, delete the existing fallback list, and create a new fallback list. If the fallback list does not exist yet, render a failure. 3. DELETE: delete the existing fallback list for a cachegroup. If the fallback list does not exist, render a failure. 4. GET: return the existing fallback list for a cachegroup. If the fallback list does not exist, render a failure. </Snip> So essentially POST creates a resource., PUT can update (replace / update) a resource which is already POST-ed. PUT can only operate on an already POST-ed resource. Does that make sense. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
