You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2019/12/04 17:56:36 UTC
[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request
#4127: Rewrite GET stats_summary from Perl to Golang
ocket8888 commented on a change in pull request #4127: Rewrite GET stats_summary from Perl to Golang
URL: https://github.com/apache/trafficcontrol/pull/4127#discussion_r353862462
##########
File path: docs/source/api/stats_summary.rst
##########
@@ -0,0 +1,175 @@
+..
+..
+.. 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-stats-summary:
+
+*****************
+``stats_summary``
+*****************
+
+``GET``
+=======
+Either retrieve a list of summary stats or the timestamp of the latest recorded stats summary.
+
+What is returned is driven by the query parameter ``lastSummaryDate``.
+
+If the parameter is set it will return an object with the latest timestamp, else an array of summary stats will be returned.
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Array or Object
+
+Request Structure
+-----------------
+
+Summary Stats
+"""""""""""""
+
+.. table:: Request Query Parameters
+
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +=====================+==========+======================================================================================================+
+ | deliveryServiceName | no | Return only summary stats that were reported for :term:`Delivery Service` with the given name |
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+ | cdnName | no | Return only summary stats that were reported for CDN with the given name |
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+ | statName | no | Return only summary stats that were reported for given stat name |
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+ | orderby | no | Choose the ordering of the results - can only be one of deliveryServiceName, statName or cdnName |
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+ | sortOrder | no | Changes the order of sorting. Either ascending (default or "asc") or |
+ | | | descending ("desc") |
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+ | limit | no | Choose the maximum number of results to return |
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+ | offset | no | The number of results to skip before beginning to return results. Must use in conjunction with limit |
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+ | page | no | Return the n\ :sup:`th` page of results, where "n" is the value of this parameter, pages are |
+ | | | ``limit`` long and the first page is 1. If ``offset`` was defined, this query parameter has no |
+ | | | effect. ``limit`` must be defined to make use of ``page``. |
+ +---------------------+----------+------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/stats_summary HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Last Updated Summary Stat
+""""""""""""""""""""""""""
+
+.. table:: Request Query Parameters
+
+ +-----------------+----------+---------------------------------------------------+
+ | Name | Required | Description |
+ +=================+==========+===================================================+
+ | statName | no | Get lastest updated date for the given stat |
+ +-----------------+----------+---------------------------------------------------+
+ | lastSummaryDate | yes | Tells route to get only lastest updated timestamp |
+ +-----------------+----------+---------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/stats_summary?lastSummaryDate=true HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+
+Summary Stats
+"""""""""""""
+
+:cdnName: CDN name summary stat was taken for
+:deliveryServiceName: :term:`Delivery Service` name summary stat was taken for
Review comment:
Display name or XMLID?
Also not a huge fan of ending these clauses with prepositions, though they don't need to be complete sentences so technically it's fine.
----------------------------------------------------------------
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:
users@infra.apache.org
With regards,
Apache Git Services