ocket8888 commented on a change in pull request #4015: Rewrite /federations to Go - POST/PUT/DELETE URL: https://github.com/apache/trafficcontrol/pull/4015#discussion_r340198521
########## File path: docs/source/api/federations.rst ########## @@ -150,82 +173,122 @@ Request Structure ----------------- No parameters available +.. code-block:: http + :caption: Request Example + + DELETE /api/1.4/federations HTTP/1.1 + Host: trafficops.infra.ciab.test + User-Agent: curl/7.47.0 + Accept: */* + Cookie: mojolicious=... + Response Structure ------------------ .. code-block:: http :caption: Response Example HTTP/1.1 200 OK Access-Control-Allow-Credentials: true - Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept + Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE Access-Control-Allow-Origin: * - Cache-Control: no-cache, no-store, max-age=0, must-revalidate Content-Type: application/json - Date: Mon, 03 Dec 2018 17:55:10 GMT - Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; expires=Mon, 03 Dec 2018 21:55:10 GMT; path=/; HttpOnly - Vary: Accept-Encoding - Whole-Content-Sha512: b84HraJH6Kiqrz7i1L1juDBJWdkdYbbClnWM0lZDljvpSkVT9adFTTrHiv7Mjtt2RKquGdzFZ6tqt9s+ODxqsw== - Content-Length: 93 - - { "response": "admin successfully deleted all federation resolvers: [ 0.0.0.0/32, ::/128 ]." } + Set-Cookie: mojolicious=...; Path=/; HttpOnly + Whole-Content-Sha512: fd7P45mIiHuYqZZW6+8K+YjY1Pe504Aaw4J4Zp9AhrqLX72ERytTqWtAp1msutzNSRUdUSC72+odNPtpv3O8uw== + X-Server-Name: traffic_ops_golang/ + Date: Wed, 23 Oct 2019 23:34:53 GMT + Content-Length: 184 + { "alerts": [ + { + "text": "admin successfully deleted all federation resolvers: [ 8.8.8.8 ]", + "level": "success" + } + ], + "response": "admin successfully deleted all federation resolvers: [ 8.8.8.8 ]" + } ``PUT`` ======= -Replaces **all** federations associated with a user's :term:`Delivery Service`\ (s) with those defined inside the request payload. +Replaces **all** :term:`Federations` associated with a user's :term:`Delivery Service`\ (s) with those defined inside the request payload. :Auth. Required: Yes :Roles Required: "admin", "Federation", "operations", "Portal", or "Steering" :Response Type: Object (string) Request Structure ----------------- -:federations: The top-level key that must exist - an array of objects that each describe a set of resolvers for a :term:`Delivery Service`'s federation +.. versionchanged:: 1.4 + Prior to API version 1.4, the request body had to be wrapped in a top-level ``federations`` key, as can be seen in the :ref:`legacy-put-request` example. That behavior is still supported but no longer necessary. - :deliveryService: The 'xml_id' of the :term:`Delivery Service` which will use the federation resolvers specified in ``mappings`` - :mappings: An object containing two arrays of IP addresses to use as federation resolvers +.. _legacy-put-request: +.. code-block:: json + :caption: Legacy Request - :resolve4: An array of IPv4 addresses that can resolve the :term:`Delivery Service`'s federation - :resolve6: An array of IPv6 addresses that can resolve the :term:`Delivery Service`'s federation + { + "federations": [{ + "deliveryService": "demo1", + "mappings": { + "resolve4": ["0.0.0.0"], + "resolve6": ["::1"] + } + }] + } + +The request payload is an array of objects that describe Delivery Service :term:`Federation` Resolver mappings. Each object in the array must be in the following format. + +:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` which will use the :term:`Federation` Resolvers specified in ``mappings`` +:mappings: An object containing two arrays of IP addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) to use as :term:`Federation` Resolvers + + :resolve4: An array of IPv4 addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) that can resolve the :term:`Delivery Service`'s :term:`Federation` + :resolve6: An array of IPv6 addresses (or subnets in :abbr:`CIDR (Classless Inter-Domain Routing)` notation) that can resolve the :term:`Delivery Service`'s :term:`Federation` .. code-block:: http :caption: Request Example PUT /api/1.4/federations HTTP/1.1 Host: trafficops.infra.ciab.test - User-Agent: curl/7.62.0 + User-Agent: curl/7.47.0 Accept: */* Cookie: mojolicious=... - Content-Length: 113 + Content-Length: 95 Content-Type: application/json - { "federations": [{ - "deliveryService": "demo1", - "mappings": { - "resolve4": ["0.0.0.1"], - "resolve6": ["::1"] - } - }]} + [{ "mappings": { + "resolve4": ["8.8.8.8"], + "resolve6": [] + }, + "deliveryService":"demo1" + }] Response Structure ------------------ .. code-block:: http :caption: Response Example HTTP/1.1 200 OK - access-control-allow-credentials: true - access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept - access-control-allow-methods: POST,GET,OPTIONS,PUT,DELETE - access-control-allow-origin: * - cache-control: no-cache, no-store, max-age=0, must-revalidate - content-type: application/json - date: Wed, 05 Dec 2018 00:52:31 GMT - server: Mojolicious (Perl) - set-cookie: mojolicious=...; expires=Wed, 05 Dec 2018 04:52:30 GMT; path=/; HttpOnly - vary: Accept-Encoding, Accept-Encoding - whole-content-sha512: dXg86uD2Un1AeBCeeBLSo2rsYgl6NOHHQEc5oMlpw1THOh2HwGdjwB3rPd/qoYIhOxcnnHoEstrEiHmucFev4A== - content-length: 63 - - {"response": "admin successfully created federation resolvers."} + Access-Control-Allow-Credentials: true + Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie + Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE + Access-Control-Allow-Origin: * + Set-Cookie: mojolicious=...; Path=/; HttpOnly + Whole-Content-Sha512: dQ5AvQULhc254zQwgUpBl1/CHbLr/clKtkbs0Ju9f1BM4xIfbbO3puFNN9zaEaZ1iz0lBvHFp/PgfUqisD3QHA== + X-Server-Name: traffic_ops_golang/ + Date: Wed, 23 Oct 2019 23:22:03 GMT + Content-Length: 258 + Content-Type: application/json + + { "alerts": { + "alerts": [ Review comment: it shouldn't - I'll check. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services