You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by mi...@apache.org on 2018/12/20 22:54:08 UTC

[trafficcontrol] branch master updated (495d1ed -> ebd295c)

This is an automated email from the ASF dual-hosted git repository.

mitchell852 pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git.


    from 495d1ed  Added a configuration setting, 'DisableHTTP2'.  The setting (#3149)
     new 155ac25  Added an explanation of the format and structure of API endpoint docs
     new ebd295c  implemented proper text roles for RFC and mimetypes

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 docs/source/admin/traffic_router.rst               |  6 +--
 docs/source/api/cdns_name_snapshot.rst             |  4 +-
 docs/source/api/cdns_name_snapshot_new.rst         |  4 +-
 .../api/deliveryservices_xmlid_urisignkeys.rst     | 24 ++++-----
 docs/source/api/index.rst                          | 59 ++++++++++++++++++----
 docs/source/api/origins.rst                        |  2 +-
 docs/source/basics/cache_revalidation.rst          |  2 +-
 docs/source/basics/http_11.rst                     |  2 +-
 8 files changed, 69 insertions(+), 34 deletions(-)


[trafficcontrol] 02/02: implemented proper text roles for RFC and mimetypes

Posted by mi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

mitchell852 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git

commit ebd295cf7c0ffe41bb3280c8eaf42200baf68bf0
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Wed Dec 19 13:21:36 2018 -0700

    implemented proper text roles for RFC and mimetypes
---
 docs/source/admin/traffic_router.rst               |  6 ++----
 docs/source/api/cdns_name_snapshot.rst             |  4 ++--
 docs/source/api/cdns_name_snapshot_new.rst         |  4 ++--
 .../api/deliveryservices_xmlid_urisignkeys.rst     | 24 +++++++++++-----------
 docs/source/api/index.rst                          |  2 +-
 docs/source/api/origins.rst                        |  2 +-
 docs/source/basics/cache_revalidation.rst          |  2 +-
 docs/source/basics/http_11.rst                     |  2 +-
 8 files changed, 22 insertions(+), 24 deletions(-)

diff --git a/docs/source/admin/traffic_router.rst b/docs/source/admin/traffic_router.rst
index 052a9bc..9cf9f8b 100644
--- a/docs/source/admin/traffic_router.rst
+++ b/docs/source/admin/traffic_router.rst
@@ -149,7 +149,7 @@ Overview
 --------
 Domain Name System Security Extensions (DNSSEC) is a set of extensions to DNS that provides a cryptographic mechanism for resolvers to verify the authenticity of responses served by an authoritative DNS server.
 
-Several RFCs (4033, 4044, 4045) describe the low level details and define the extensions, RFC 7129 provides clarification around authenticated denial of existence of records, and finally RFC 6781 describes operational best practices for administering an authoritative DNSSEC enabled DNS server. The authenticated denial of existence RFC describes how an authoritative DNS server responds in NXDOMAIN and NODATA scenarios when DNSSEC is enabled.
+Several RFCs (:rfc:`4033`, :rfc:`4044`, :rfc:`4045`) describe the low level details and define the extensions, :rfc:`7129` provides clarification around authenticated denial of existence of records, and finally RFC 6781 describes operational best practices for administering an authoritative DNSSEC enabled DNS server. The authenticated denial of existence RFC describes how an authoritative DNS server responds in NXDOMAIN and NODATA scenarios when DNSSEC is enabled.
 
 Traffic Router currently supports DNSSEC with NSEC, however, NSEC3 and more configurable options are planned for the future.
 
@@ -165,9 +165,7 @@ To enable DNSSEC for a CDN in Traffic Portal, Go to 'CDNs' from the sidebar and
 
 Rolling Zone Signing Keys
 -------------------------
-Traffic Router currently follows the zone signing key pre-publishing operational best practice described in `section 4.1.1.1 of RFC 6781`_. Once DNSSEC is enabled for a CDN in Traffic Portal, key rolls are triggered by Traffic Ops via the automated key generation process, and Traffic Router selects the active zone signing keys based on the expiration information returned from the 'keystore' API of Traffic Ops.
-
-.. _section 4.1.1.1 of RFC 6781: https://tools.ietf.org/html/rfc6781#section-4.1.1.1
+Traffic Router currently follows the zone signing key pre-publishing operational best practice described in :rfc:`6781#section-4.1.1.1`. Once DNSSEC is enabled for a CDN in Traffic Portal, key rolls are triggered by Traffic Ops via the automated key generation process, and Traffic Router selects the active zone signing keys based on the expiration information returned from the 'keystore' API of Traffic Ops.
 
 .. _tr-logs:
 
diff --git a/docs/source/api/cdns_name_snapshot.rst b/docs/source/api/cdns_name_snapshot.rst
index facc93b..2e00eba 100644
--- a/docs/source/api/cdns_name_snapshot.rst
+++ b/docs/source/api/cdns_name_snapshot.rst
@@ -97,7 +97,7 @@ Response Structure
 		:refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
 		:retry:   A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
 
-			.. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+			.. note:: :rfc:`1035` dictates that this should always be less than ``refresh``.
 
 		.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
 
@@ -253,7 +253,7 @@ Response Structure
 		:refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
 		:retry:   A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
 
-			.. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+			.. note:: :rfc:`1035` dictates that this should always be less than ``refresh``.
 
 		.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
 
diff --git a/docs/source/api/cdns_name_snapshot_new.rst b/docs/source/api/cdns_name_snapshot_new.rst
index b2238b8..d981f3c 100644
--- a/docs/source/api/cdns_name_snapshot_new.rst
+++ b/docs/source/api/cdns_name_snapshot_new.rst
@@ -96,7 +96,7 @@ Response Structure
 		:refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
 		:retry:   A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
 
-			.. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+			.. note:: :rfc:`1035` dictates that this should always be less than ``refresh``.
 
 		.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
 
@@ -252,7 +252,7 @@ Response Structure
 		:refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
 		:retry:   A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
 
-			.. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+			.. note:: :rfc:`1035` dictates that this should always be less than ``refresh``.
 
 		.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
 
diff --git a/docs/source/api/deliveryservices_xmlid_urisignkeys.rst b/docs/source/api/deliveryservices_xmlid_urisignkeys.rst
index 996f1a5..039136e 100644
--- a/docs/source/api/deliveryservices_xmlid_urisignkeys.rst
+++ b/docs/source/api/deliveryservices_xmlid_urisignkeys.rst
@@ -62,13 +62,13 @@ DELETE
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
 	| ``keys``            | string | json array of jwt symmetric keys                                                             .                                          |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``alg``             | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, RFC 7518.         |
+	| ``alg``             | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518`       |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``kid``             | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in RFC 7516.                    |
+	| ``kid``             | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516`                  |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``kty``             | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in RFC 7516.                                 |
+	| ``kty``             | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516`                               |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``k``               | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see RFC 7516.                       |
+	| ``k``               | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516`                     |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
 
 	**Response Example** ::
@@ -121,13 +121,13 @@ DELETE
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
 	| ``keys``            | string | json array of jwt symmetric keys                                                             .                                          |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``alg``             | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, RFC 7518.         |
+	| ``alg``             | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518`       |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``kid``             | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in RFC 7516.                    |
+	| ``kid``             | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516`                  |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``kty``             | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in RFC 7516.                                 |
+	| ``kty``             | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516`                               |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``k``               | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see RFC 7516.                       |
+	| ``k``               | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516`                     |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
 
 	**Request Example** ::
@@ -179,13 +179,13 @@ DELETE
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
 	| ``keys``            | string | json array of jwt symmetric keys                                                             .                                          |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``alg``             | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, RFC 7518.         |
+	| ``alg``             | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518`       |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``kid``             | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in RFC 7516.                    |
+	| ``kid``             | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516`                  |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``kty``             | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in RFC 7516.                                 |
+	| ``kty``             | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516`                               |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
-	| ``k``               | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see RFC 7516.                       |
+	| ``k``               | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516`                     |
 	+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
 
 	**Request Example** ::
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index e5cb648..1a24dbc 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -53,7 +53,7 @@ The methods of endpoints that require/accept data payloads - unless otherwise no
 
 All fields are mandatory in a request payload, or always present in a response payload unless otherwise noted in the field description.
 
-In most cases, JSON objects have been "pretty-printed" by inserting line breaks and indentation. This means that the ``Content-Length`` HTTP header does not, in general, accurately portray the length of the content displayed in Request Examples and Response Examples. Also, the Traffic Ops endpoints will ignore any content negotiation, meaning that the ``Content-Type`` header of a request is totally meaningless. A utility may choose to pass the data as e.g. ``application/x-www-form-urlenc [...]
+In most cases, JSON objects have been "pretty-printed" by inserting line breaks and indentation. This means that the ``Content-Length`` HTTP header does not, in general, accurately portray the length of the content displayed in Request Examples and Response Examples. Also, the Traffic Ops endpoints will ignore any content negotiation, meaning that the ``Content-Type`` header of a request is totally meaningless. A utility may choose to pass the data as e.g. :mimetype:`application/x-www-fo [...]
 
 .. _to-api-response-structure:
 
diff --git a/docs/source/api/origins.rst b/docs/source/api/origins.rst
index 8165cdc..cdece7d 100644
--- a/docs/source/api/origins.rst
+++ b/docs/source/api/origins.rst
@@ -13,7 +13,7 @@
 .. limitations under the License.
 ..
 
-.. _to-api-origin:
+.. _to-api-origins:
 
 ***********
 ``origins``
diff --git a/docs/source/basics/cache_revalidation.rst b/docs/source/basics/cache_revalidation.rst
index 8af957d..3aa0c48 100644
--- a/docs/source/basics/cache_revalidation.rst
+++ b/docs/source/basics/cache_revalidation.rst
@@ -20,7 +20,7 @@
 
 Cache Control Headers and Revalidation
 ======================================
-The `HTTP/1.1 spec <https://www.ietf.org/rfc/rfc2616.txt>`_ allows for origin servers and clients to influence how caches treat their requests and responses. By default, the Traffic Control CDN will honor cache control headers. Most commonly, origin servers will tell the downstream caches how long a response can be cached
+The HTTP/1.1 spec :rfc:`2616` allows for origin servers and clients to influence how caches treat their requests and responses. By default, the Traffic Control CDN will honor cache control headers. Most commonly, origin servers will tell the downstream caches how long a response can be cached
 
 .. code-block:: http
 	:caption: This Response may Only be Cached for 86400 Seconds
diff --git a/docs/source/basics/http_11.rst b/docs/source/basics/http_11.rst
index 9283248..816c876 100644
--- a/docs/source/basics/http_11.rst
+++ b/docs/source/basics/http_11.rst
@@ -21,7 +21,7 @@ HTTP/1.1
 ========
 For a comprehensive look at Traffic Control, it is important to understand basic HTTP/1.1 protocol operations and how caches function. The example below illustrates the fulfillment of an HTTP/1.1 request in a situation without CDN or proxy, followed by viewing the changes after inserting different types of (caching) proxies. Several of the examples below are simplified for clarification of the essentials.
 
-For complete details on HTTP/1.1 see `RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1 <https://www.ietf.org/rfc/rfc2616.txt>`_.
+For complete details on HTTP/1.1 see :rfc:`2616`.
 
 Below are the steps of a client retrieving the URL ``http://www.origin.com/foo/bar/fun.html`` using HTTP/1.1 without proxies:
 


[trafficcontrol] 01/02: Added an explanation of the format and structure of API endpoint docs

Posted by mi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

mitchell852 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git

commit 155ac25f8cf3ace84cf9b0039d5670b79ae7899c
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Mon Dec 17 11:39:18 2018 -0700

    Added an explanation of the format and structure of API endpoint docs
---
 docs/source/api/index.rst | 59 ++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 48 insertions(+), 11 deletions(-)

diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index ca9cd60..e5cb648 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -30,19 +30,54 @@ API Routes
 
 	*
 
+How to Read this Documentation
+==============================
+Each endpoint is on its own page, titled with the request path. The request paths shown on each endpoint's page are - unless otherwise noted - only usable by being appended to the request path prefix ``/api/<version>/`` where ``<version>`` is the API version being requested. The API versions officially supported as of the time of this writing are 1.1, 1.2, 1.3, 1.4. All endpoints are documented as though they were being used in version 1.4. If an endpoint or request method of an endpoint [...]
+
+Every endpoint is documented with a section for each method, containing the subsections "Request Structure" and "Response Structure" which identify all properties and structure of the Request to and Response from the endpoint. Before these subsections, three key pieces of information will be provided:
+
+Auth. Required
+	This will either be 'Yes' to indicate that a user must be authenticated (or "logged-in") via e.g. :ref:`to-api-user-login` to use this method of the endpoint, or 'No' to indicate that this is not required.
+Roles Required
+	Any permissions roles that are allowed to use this method of the endpoint will be listed here. Users with roles not listed here will be unable to properly use these endpoints
+Response Type
+	Unless otherwise noted, all responses are JSON objects. See `Response Structure`_ for more information.
+
+The methods of endpoints that require/accept data payloads - unless otherwise noted - always interpret the content of the payload as a JSON object, regardless of the request's ``Content-Type`` header. Because of this, all payloads are - unless otherwise noted - JSON objects. The Request Structure and Response Structure subsections will contain explanations of the fields before any examples like e.g.
+
+:foo: A constant field that always contains "foo"
+:bar: An array of objects that each represent a "bar" object
+
+	:name:  The bar's name
+	:value: The bar's value (an integer)
+
+All fields are mandatory in a request payload, or always present in a response payload unless otherwise noted in the field description.
+
+In most cases, JSON objects have been "pretty-printed" by inserting line breaks and indentation. This means that the ``Content-Length`` HTTP header does not, in general, accurately portray the length of the content displayed in Request Examples and Response Examples. Also, the Traffic Ops endpoints will ignore any content negotiation, meaning that the ``Content-Type`` header of a request is totally meaningless. A utility may choose to pass the data as e.g. ``application/x-www-form-urlenc [...]
+
 .. _to-api-response-structure:
 
 Response Structure
-==================
-All successful responses have the following structure:
+------------------
+Unless otherwise noted, all response payloads come as JSON objects.
 
 .. code-block:: json
+	:caption: Response Structure
 
 	{
 		"response": "<JSON object with main response>",
 	}
 
-To make the documentation easier to read, only the ``<JSON object with main response>`` is documented, even though the response endpoints may return other top-level objects (most commonly the ``"alerts"`` object.
+To make the documentation easier to read, only the ``<JSON object with main response>`` is documented, even though the response endpoints may return other top-level objects (most commonly the ``"alerts"`` object). The field definitions listed in the Response Structure subsection of an endpoint method are the elements of this object. Sometimes the ``response`` object is a string, sometimes it's an object that maps keys to values, sometimes it's an array that contains many arbitrary object [...]
+
+Response Type Meanings
+""""""""""""""""""""""
+Array
+	The fields in the field list refer to the keys of the objects in the ``response`` array.
+Object
+	The fields in the field list refer to the keys of the ``response`` object.
+``undefined``
+	No ``response`` object is present in the response payload. Unless the format is otherwise noted, this means that there should be no field list in the "Response Structure" subsection.
 
 Using API Endpoints
 ===================
@@ -53,6 +88,8 @@ Using API Endpoints
 
 #. Pass the Mojolicious cookie value, along with any subsequent calls to an authenticated API endpoint.
 
+.. note:: Many endpoints support a ``.json`` suffix. This should be avoided at all costs, because there's no real consistency regarding when it may be used, and the output of API endpoints, in general, are not capable of representing POSIX-compliant files (as a 'file extension' might imply).
+
 Example Session
 ---------------
 A user makes a request to the ``/api/1.1/asns`` endpoint.
@@ -99,7 +136,7 @@ Traffic Ops responds with a Mojolicious cookie to be used for future requests, a
 	Connection: keep-alive
 	Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
 	Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
-	Set-Cookie: mojolicious=eyJhdXRoX2RhdGEiOiJhZG1pbiIsImV4cGlyZXMiOjE1Mzg1MDY5OTgsImJ5IjoidHJhZmZpY2NvbnRyb2wtZ28tdG9jb29raWUifQ--bcc9aade79b6de436cb4962ef5cec397f7ac5bd2; Path=/; Expires=Tue, 02 Oct 2018 19:03:18 GMT; HttpOnly
+	Set-Cookie: mojolicious=...; Path=/; Expires=Tue, 02 Oct 2018 19:03:18 GMT; HttpOnly
 	Content-Type: application/json
 	Date: Tue, 02 Oct 2018 12:53:32 GMT
 	Access-Control-Allow-Credentials: true
@@ -119,7 +156,7 @@ Using this cookie, the user can now access their original target - the ``/api/1.
 
 	GET /api/1.1/asns HTTP/1.1
 	Accept: application/json
-	Cookie: mojolicious=eyJleHBpcmVzIjoxNDI5NDAyMjAxLCJhdXRoX2RhdGEiOiJhZG1pbiJ9--f990d03b7180b1ece97c3bb5ca69803cd6a79862;
+	Cookie: mojolicious=...;
 	Host: trafficops.infra.ciab.test
 	User-Agent: Example
 
@@ -137,7 +174,7 @@ Using this cookie, the user can now access their original target - the ``/api/1.
 	Content-Length: 48
 	Content-Type: application/json
 	Date: Tue, 02 Oct 2018 12:55:57 GMT
-	Set-Cookie: mojolicious=eyJhdXRoX2RhdGEiOi…ccd4eae46c6; Path=/; HttpOnly
+	Set-Cookie: mojolicious=...; Path=/; HttpOnly
 	Whole-Content-SHA512: u+Q5X7z/DMTc/VzRGaFlJBA8btA8EC…dnA85HCYTm8vVwsQCvle+uVc1nA==
 	X-Server-Name: traffic_ops_golang/
 
@@ -164,13 +201,13 @@ API Errors
 ==========
 If an API endpoint has something to say besides the actual response (usually an error message), it will add a top-level object to the response JSON with the key ``"alerts"``. This will be an array of objects that represent messages from the server, each with the following string fields:
 
-:``level``: ``"success"``, ``"info"``, ``"warning"`` or ``"error"`` as appropriate
-:``text``: The alert's actual message
+:level: ``"success"``, ``"info"``, ``"warning"`` or ``"error"`` as appropriate
+:text: The alert's actual message
 
 The most common errors returned by Traffic Ops are:
 
 401 Unauthorized
-	When a Mojolicious cookie is supplied that is invalid or expired, or the login credentials are incorrect the server responds with a ``401 UNAUTHORIZED`` response code.
+	When a "mojolicious" cookie is supplied that is invalid or expired, or the login credentials are incorrect the server responds with a ``401 UNAUTHORIZED`` response code.
 
 	.. code-block:: http
 		:caption: Example of a Response to a Login Request with Bad Credentials
@@ -208,7 +245,7 @@ The most common errors returned by Traffic Ops are:
 		Content-Type: text/html;charset=UTF-8
 		Date: Tue, 02 Oct 2018 13:58:56 GMT
 		Server: Mojolicious (Perl)
-		Set-Cookie: mojolicious=eyJhdXRoX2RhdGEiOiJhZG1pbiIsImV4cGlyZXMiOjE1Mzg1MDMxMzYsImJ5IjoidHJhZmZpY2NvbnRyb2wtZ28tdG9jb29raWUifQ----9b144306f8bb6020eadb950647b3dc0eebeb7eae; expires=Tue, 02 Oct 2018 17:58:56 GMT; path=/; HttpOnly
+		Set-Cookie: mojolicious=...; expires=Tue, 02 Oct 2018 17:58:56 GMT; path=/; HttpOnly
 		Vary: Accept-Encoding
 		Whole-Content-Sha512: Ff5hO8ZUNUMbwCW0mBuUlsvrSmm/Giijpq7O3uLivLZ6VOu6eGom4Jag6UqlBbbDBnP6AG7l1Szdt74TT6NidA==
 		Transfer-Encoding: chunked
@@ -231,7 +268,7 @@ The most common errors returned by Traffic Ops are:
 		Content-Type: application/json
 		Date: Tue, 02 Oct 2018 17:29:42 GMT
 		Server: Mojolicious (Perl)
-		Set-Cookie: mojolicious=eyJhdXRoX2RhdGEiOiJhZG1pbiIsImV4cGlyZXMiOjE0Mjk0MDQzMDZ9--1b08977e91f8f68b0ff5d5e5f6481c76ddfd0853; expires=Sun, 19 Apr 2015 00:45:06 GMT; path=/; HttpOnly
+		Set-Cookie: mojolicious=..; expires=Sun, 19 Apr 2015 00:45:06 GMT; path=/; HttpOnly
 		Vary: Accept-Encoding
 		Whole-Content-Sha512: gFa4NYFmofCbV7YqgwyFRzKk90+KNgoZu6p2Nx98J4Gy7/2j55tYknvk53WXuMdMKKrgYMop4uiYOla1k1ozQQ==