mitchell852 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_r178165822
########## 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: yes, it makes sense but i don't really understand why you'd want 4 endpoints with extra logic in the POST and PUT endpoints (if exists, fail or if not exists, fail). Instead if you just make the POST do a delete all/create (which is really a replace), then it can be used in both scenarios. then there becomes no confusion about the difference between POST and PUT ---------------------------------------------------------------- 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
