[GitHub] [trafficcontrol] ocket8888 commented on a diff in pull request #6869: Update Traffic Ops API v2 usage to API v4

[GitBox <gi...@apache.org>]

ocket8888 commented on code in PR #6869:
URL: https://github.com/apache/trafficcontrol/pull/6869#discussion_r886909250


##########
docs/source/admin/quick_howto/ciab.rst:
##########
@@ -254,7 +254,7 @@ The "enroller" began as an efficient way for Traffic Ops to be populated with da
 	The name of a file which will be created in the :option:`--dir` directory when given, indicating service was started (default: "enroller-started").
 
 
-The enroller runs within CDN in a Box using :option:`--dir` which provides the above behavior. It can also be run using :option:`--http` to instead have it listen on the indicated port. In this case, it accepts only ``POST`` requests with the JSON provided in the request payload, e.g. ``curl -X POST https://enroller/api/2.0/regions -d @newregion.json``. CDN in a Box does not currently use this method, but may be modified in the future to avoid using the shared volume approach.
+The enroller runs within CDN in a Box using :option:`--dir` which provides the above behavior. It can also be run using :option:`--http` to instead have it listen on the indicated port. In this case, it accepts only ``POST`` requests with the JSON provided in the request payload, e.g. ``curl -X POST https://enroller/api/4.0/regions -d @newregion.json``. CDN in a Box does not currently use this method, but may be modified in the future to avoid using the shared volume approach.

Review Comment:
   Is the enroller's "API" really versioned? I feel like we should just have it use the path segments following the API version and automagically use the latest version its client knows about.
   
   Which doesn't need to be addressed by this PR, necessarily, but I wanted to bring it up in case I forget.



##########
docs/source/admin/quick_howto/ciab.rst:
##########
@@ -237,7 +237,7 @@ This section will be amended as functionality is added to the CDN in a Box proje
 
 The Enroller
 ------------
-The "enroller" began as an efficient way for Traffic Ops to be populated with data as CDN in a Box starts up. It connects to Traffic Ops as the "admin" user and processes files places in the docker volume shared between the containers. The enroller watches each directory within the ``/shared/enroller`` directory for new :file:`{filename}.json` files to be created there. These files must follow the format outlined in the API guide for the ``POST`` method for each data type,  (e.g. for a ``region``, follow the guidelines for ``POST api/2.0/regions``). Of note, the ``enroller`` does not require fields that reference database ids for other objects within the database.
+The "enroller" began as an efficient way for Traffic Ops to be populated with data as CDN in a Box starts up. It connects to Traffic Ops as the "admin" user and processes files places in the docker volume shared between the containers. The enroller watches each directory within the ``/shared/enroller`` directory for new :file:`{filename}.json` files to be created there. These files must follow the format outlined in the API guide for the ``POST`` method for each data type,  (e.g. for a ``region``, follow the guidelines for ``POST api/4.0/regions``). Of note, the ``enroller`` does not require fields that reference database ids for other objects within the database.

Review Comment:
   Instead of stating the name and specific version of an endpoint, this should just link to the `to-api-regions` label like so:
   ```rst
   ... follow the guidelines for the ``POST`` method of the :ref:`to-api-regions` endpoint. ...
   ```
   
   ... or you could make a label on that endpoint's documentation specifically for the POST method if you want, and link that with custom link text.



-- 
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.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org