mitchell852 closed pull request #2586: updated documentation for the StaticDNSEntries API URL: https://github.com/apache/trafficcontrol/pull/2586
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/CHANGELOG.md b/CHANGELOG.md index ade8dc899..123734cce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/). - Traffic Ops Golang Proxy Endpoints - /api/1.3/origins `(GET,POST,PUT,DELETE)` - /api/1.3/coordinates `(GET,POST,PUT,DELETE)` + - /api/1.3/staticdnsentries `(GET,POST,PUT,DELETE)` - Delivery Service Origins Refactor: The Delivery Service API now creates/updates an Origin entity on Delivery Service creates/updates, and the `org_server_fqdn` column in the `deliveryservice` table has been removed. The `org_server_fqdn` data is now computed from the Delivery Service's primary origin (note: the name of the primary origin is the `xml_id` of its delivery service). - Cachegroup-Coordinate Refactor: The Cachegroup API now creates/updates a Coordinate entity on Cachegroup creates/updates, and the `latitude` and `longitude` columns in the `cachegroup` table have been replaced with `coordinate` (a foreign key to Coordinate). Coordinates created from Cachegroups are given the name `from_cachegroup_\<cachegroup name\>`. - Geolocation-based Client Steering: two new steering target types are available to use for `CLIENT_STEERING` delivery services: `STEERING_GEO_ORDER` and `STEERING_GEO_WEIGHT`. When targets of these types have an Origin with a Coordinate, Traffic Router will order and prioritize them based upon the shortest total distance from client -> edge -> origin. Co-located targets are grouped together and can be weighted or ordered within the same location using `STEERING_GEO_WEIGHT` or `STEERING_GEO_ORDER`, respectively. diff --git a/docs/source/api/v13/index.rst b/docs/source/api/v13/index.rst index 67749099b..64f9cde8b 100644 --- a/docs/source/api/v13/index.rst +++ b/docs/source/api/v13/index.rst @@ -23,3 +23,4 @@ Traffic Ops API V1.3 coordinate origin + staticdnsentry diff --git a/docs/source/api/v13/staticdnsentry.rst b/docs/source/api/v13/staticdnsentry.rst new file mode 100644 index 000000000..53b7f6564 --- /dev/null +++ b/docs/source/api/v13/staticdnsentry.rst @@ -0,0 +1,317 @@ +.. +.. +.. 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-v13-staticdnsentries: + +StaticDNSEntries +================ + +.. _to-api-v13-static-dns-entry-route: + +/api/1.3/staticdnsentries ++++++++++++++++++++++++++ + +**GET /api/1.3/staticdnsentries** + + Authentication Required: Yes + + Role(s) Required: None + + **Request Query Parameters** + + +-----------------------+----------+-------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +=======================+==========+===========================================================================================+ + | ``id`` | no | Filter StaticDNSEntries by id. | + +-----------------------+----------+-------------------------------------------------------------------------------------------+ + | ``address`` | no | Filter StaticDNSENtries by address. | + | ``cachegroup`` | no | Filter StaticDNSENtries by cachegroup name. | + | ``cachegroupId`` | no | Filter StaticDNSENtries by cachegroup id. | + | ``deliveryservice`` | no | Filter StaticDNSENtries by deliveryservice (xml_id). | + | ``deliveryserviceId`` | no | Filter StaticDNSENtries by deliveryserviceId. | + | ``host`` | no | Filter StaticDNSENtries by host. | + | ``ttl`` | no | Filter StaticDNSENtries by ttl. | + | ``type`` | no | Filter StaticDNSENtries by type (valid types are A_RECORD, AAAA_RECORD and CNAME_RECORD). | + | ``typeId`` | no | Filter StaticDNSENtries by typeId. | + +-----------------------+----------+-------------------------------------------------------------------------------------------+ + + **Response Properties** + + +-----------------------+--------+---------------------------------------------+ + | Parameter | Type | Description | + +=======================+========+=============================================+ + | ``address`` | string | The fully qualified domain name (FQDN) | + +-----------------------+--------+---------------------------------------------+ + | ``cachegroup`` | string | The Cachegroup Name | + +-----------------------+--------+---------------------------------------------+ + | ``cachegroupId`` | int | The Cachegroup id | + +-----------------------+--------+---------------------------------------------+ + | ``deliveryservice`` | string | The DeliveryService Name | + +-----------------------+--------+---------------------------------------------+ + | ``deliveryserviceId`` | int | The DeliveryService id | + +-----------------------+--------+---------------------------------------------+ + | ``host`` | string | The hostname | + +-----------------------+--------+---------------------------------------------+ + | ``id`` | int | Local unique identifier | + +-----------------------+--------+---------------------------------------------+ + | ``lastUpdated`` | string | The Time / Date this entry was last updated | + +-----------------------+--------+---------------------------------------------+ + | ``ttl`` | int | The Total Time to Live | + +-----------------------+--------+---------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "address": "this.one.is.a.hostname", + "cachegroup": "cachegroup1", + "cachegroupId": 18, + "deliveryservice": "ds1", + "deliveryserviceId": 28, + "lastUpdated": "2012-09-25 20:27:28", + "host": "host1", + "id": 21, + "ttl": 30, + "type": "CNAME_RECORD", + "typeId": 19 + }, + { + "address": "this.two.is.a.hostname", + "cachegroup": "cachegroup2", + "cachegroupId": 18, + "deliveryservice": "ds1", + "deliveryserviceId": 30, + "lastUpdated": "2012-09-25 20:27:28", + "host": "host2", + "id": 22, + "ttl": 10, + "type": "A_RECORD", + "typeId": 18 + } + ] + } + +| + +**POST /api/1.3/staticdnsentries** + + Create a StaticDNSEntry. + + Authentication Required: Yes + + Role(s) Required: admin or oper + + **Request Parameters** + + +-----------------------+----------+----------------------------------------+ + | Name | Required | Description | + +=======================+==========+========================================+ + | ``address`` | yes | The fully qualified domain name (FQDN) | + +-----------------------+----------+----------------------------------------+ + | ``cachegroupId`` | yes | The Cachegroup id | + +-----------------------+----------+----------------------------------------+ + | ``deliveryserviceId`` | yes | The DeliveryService id | + +-----------------------+----------+----------------------------------------+ + | ``host`` | yes | The hostname | + +-----------------------+----------+----------------------------------------+ + | ``ttl`` | yes | The Total Time to Live | + +-----------------------+----------+----------------------------------------+ + + **Request Example** :: + + { + "address": "this.one.is.a.hostname", + "cachegroupId": 18, + "deliveryserviceId": 20, + "host": 20, + "ttl": 10 + } + + **Response Properties** + + +-----------------------+--------+----------------------------------------+ + | Parameter | Type | Description | + +=======================+========+========================================+ + | ``id`` | int | The id of the StaticDNSEntry | + +-----------------------+--------+----------------------------------------+ + | ``address`` | string | The fully qualified domain name (FQDN) | + +-----------------------+--------+----------------------------------------+ + | ``cachegroupId`` | int | The Cachegroup id | + +-----------------------+--------+----------------------------------------+ + | ``deliveryserviceId`` | int | The DeliveryService id | + +-----------------------+--------+----------------------------------------+ + | ``host`` | string | The hostname | + +-----------------------+--------+----------------------------------------+ + | ``ttl`` | int | The Total Time to Live | + +-----------------------+--------+----------------------------------------+ + | ``alerts`` | array | A collection of alert messages. | + +-----------------------+--------+----------------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +-----------------------+--------+----------------------------------------+ + | ``>text`` | string | Alert message. | + +-----------------------+--------+----------------------------------------+ + + **Response Example** :: + + { + "alerts": [ + { + "level": "success", + "text": "staticdnsentry was created" + } + ], + "response": { + "address": "this.one.is.a.hostname", + "cachegroupId": 18, + "deliveryserviceId": 20, + "lastUpdated" : "2016-01-25 13:55:30", + "host": 20, + "id" : 1, + "ttl": 10 + } + } + +| + +**PUT /api/1.3/staticdnsentries** + + Update staticdnsentries. + + Authentication Required: Yes + + Role(s) Required: admin or oper + + **Request Query Parameters** + + +------+----------+---------------------------------------+ + | Name | Required | Description | + +======+==========+=======================================+ + | id | yes | The id of the staticdnsentry to edit. | + +------+----------+---------------------------------------+ + + **Request Parameters** + + +-----------------------+----------+----------------------------------------+ + | Name | Required | Description | + +=======================+==========+========================================+ + | ``address`` | yes | The fully qualified domain name (FQDN) | + +-----------------------+----------+----------------------------------------+ + | ``cachegroupId`` | yes | The Cachegroup id | + +-----------------------+----------+----------------------------------------+ + | ``deliveryserviceId`` | yes | The DeliveryService id | + +-----------------------+----------+----------------------------------------+ + | ``host`` | yes | The hostname | + +-----------------------+----------+----------------------------------------+ + | ``ttl`` | yes | The Total Time to Live | + +-----------------------+----------+----------------------------------------+ + + **Request Example** :: + + { + "address": "this.one.is.a.hostname", + "cachegroupId": 18, + "deliveryserviceId": 20, + "host": 20, + "ttl": 10 + } + + **Response Properties** + + +-----------------------+--------+----------------------------------------+ + | Parameter | Type | Description | + +=======================+========+========================================+ + | ``id`` | int | The id of the StaticDNSEntry | + +-----------------------+--------+----------------------------------------+ + | ``address`` | string | The fully qualified domain name (FQDN) | + +-----------------------+--------+----------------------------------------+ + | ``cachegroupId`` | int | The Cachegroup id | + +-----------------------+--------+----------------------------------------+ + | ``deliveryserviceId`` | int | The DeliveryService id | + +-----------------------+--------+----------------------------------------+ + | ``host`` | string | The hostname | + +-----------------------+--------+----------------------------------------+ + | ``ttl`` | int | The Total Time to Live | + +-----------------------+--------+----------------------------------------+ + | ``alerts`` | array | A collection of alert messages. | + +-----------------------+--------+----------------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +-----------------------+--------+----------------------------------------+ + | ``>text`` | string | Alert message. | + +-----------------------+--------+----------------------------------------+ + + **Response Example** :: + + { + "alerts": [ + { + "level": "success", + "text": "staticdnsentry was updated" + } + ], + "response": { + "address": "this.one.is.a.hostname", + "cachegroupId": 18, + "deliveryserviceId": 20, + "lastUpdated" : "2016-01-25 13:55:30", + "host": 20, + "id" : 1, + "ttl": 10 + } + } + +| + +**DELETE /api/1.3/staticdnsentries** + + Delete staticdnsentries. + + Authentication Required: Yes + + Role(s) Required: admin or oper + + **Request Query Parameters** + + +------+----------+-----------------------------------------+ + | Name | Required | Description | + +======+==========+=========================================+ + | id | yes | The id of the staticdnsentry to delete. | + +------+----------+-----------------------------------------+ + + **Response Properties** + + +-------------+--------+----------------------------------+ + | Parameter | Type | Description | + +=============+========+==================================+ + | ``alerts`` | array | A collection of alert messages. | + +-------------+--------+----------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +-------------+--------+----------------------------------+ + | ``>text`` | string | Alert message. | + +-------------+--------+----------------------------------+ + + **Response Example** :: + + { + "alerts": [ + { + "level": "success", + "text": "staticdnsentry was deleted" + } + ] + } + +| + ---------------------------------------------------------------- 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
