Deprecate servers/hostname/hostName/details

CHANGELOG.md

@@ -91,6 +91,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
   - /riak/ping
   - /riak/stats
   - /servercheck/aadata
+  - /servers/hostname/:hostName/details
   - /servers/status
   - /servers/:id (GET)
   - /servers/totals

docs/source/api/v1/servers_hostname_name_details.rst

@@ -18,6 +18,8 @@
 *************************************
 ``servers/hostname/{{name}}/details``
 *************************************
+.. deprecated:: ATCv4
+	Use the ``GET`` method of :ref:`to-api-servers-details` with the query parameter ``hostName`` instead.
 
 ``GET``
 =======
@@ -136,6 +138,12 @@ Response Structure
 		"iloIpAddress": "",
 		"profileDesc": "Edge Cache - Apache Traffic Server",
 		"routerHostName": ""
-	}}
+	},
+	"alerts": [
+		{
+			"text": "This endpoint is deprecated, please use GET /servers/details with query parameter hostName instead",
+			"level": "warning"
+		}
+	]}
 
 .. [1] For more information see the `Wikipedia page on Lights-Out management <https://en.wikipedia.org/wiki/Out-of-band_management>`_\ .

docs/source/api/v2/servers_details.rst

@@ -0,0 +1,168 @@
+..
+..
+.. 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-servers-details:
+
+*******************
+``servers/details``
+*******************
+Retrieves details of :ref:`tp-configure-servers`.
+
+
+``GET``
+=======
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type:  Array
+
+.. note:: On top of the response including the response key that is of type array it will also include the keys ``limit``, ``orderby``, and ``size``.
+
+Request Structure
+-----------------
+.. table:: Request Query Parameters
+
+	+----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+	| Name           | Required                               | Description                                                                                                                                                    |
+	+================+========================================+================================================================================================================================================================+
+	| hostName       | Required if no physLocationID provided | Return only the servers with this (short) hostname. Capitalization of "hostName" is important.                                                                 |
+	+----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+	| physLocationID | Required if no hostName provided       | Return only servers with this integral, unique identifier for the physical location where the server resides. Capitalization of "physLocationID" is important. |
+	+----------------+----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. code-block:: http
+	:caption: Request Example
+
+	GET /api/2.0/servers/details?hostName=edge HTTP/1.1
+	User-Agent: python-requests/2.22.0
+	Accept-Encoding: gzip, deflate
+	Accept: */*
+	Connection: keep-alive
+	Cookie: mojolicious=...
+
+Response Structure
+------------------
+:limit:		The maximum size of the ``response`` array, also indicative of the number of results per page using the pagination requested by the query parameters (if any) - this should be the same as the ``limit`` query parameter (if given)
+:orderby:	A string that names the field by which the elements of the ``response`` array are ordered - should be the same as the ``orderby`` request query parameter (if given)
+:response:	An array of objects, each of which represents the details of a given :ref:`Server <tp-configure-servers>`.
+
+	:cachegroup:		A string that is the :ref:`name of the Cache Group <cache-group-name>` to which the server belongs
+	:cdnName:		Name of the CDN to which the server belongs
+	:deliveryservices:	An array of integral, unique identifiers for :term:`Delivery Services` to which this server belongs
+	:domainName:		The domain part of the server's :abbr:`FQDN (Fully Qualified Domain Name)`
+	:guid:			An identifier used to uniquely identify the server
+
+		.. note::	This is a legacy key which only still exists for compatibility reasons - it should always be ``null``
+
+	:hostName:		The (short) hostname of the server
+	:httpsPort:		The port on which the server listens for incoming HTTPS connections/requests
+	:id:			An integral, unique identifier for this server
+	:iloIpAddress:		The IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+	:iloIpGateway:		The IPv4 gateway address of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+	:iloIpNetmask:		The IPv4 subnet mask of the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+	:iloPassword:		The password of the of the server's :abbr:`ILO (Integrated Lights-Out)` service user\ [1]_ - displays as simply ``******`` if the currently logged-in user does not have the 'admin' or 'operations' :term:`Role(s) <Role>`
+	:iloUsername:		The user name for the server's :abbr:`ILO (Integrated Lights-Out)` service\ [1]_
+	:interfaceMtu:		The :abbr:`MTU (Maximum Transmission Unit)` to configured on ``interfaceName``
+	:interfaceName:		The name of the primary network interface used by the server
+	:ip6Address:		The IPv6 address and subnet mask of ``interfaceName``
+	:ip6Gateway:		The IPv6 address of the gateway used by ``interfaceName``
+	:ipAddress:		The IPv4 address of ``interfaceName``
+	:ipGateway:		The IPv4 address of the gateway used by ``interfaceName``
+	:ipNetmask:		The IPv4 subnet mask used by ``interfaceName``
+	:offlineReason:		A user-entered reason why the server is in ADMIN_DOWN or OFFLINE status
+	:physLocation:		The name of the physical location where the server resides
+	:profile:		The :ref:`profile-name` of the :term:`Profile` used by this server
+	:profileDesc:		A :ref:`profile-description` of the :term:`Profile` used by this server
+	:rack:	A string indicating "server rack" location
+	:routerHostName:	The human-readable name of the router responsible for reaching this server
+	:routerPortName:	The human-readable name of the port used by the router responsible for reaching this server
+	:status:		The status of the server
+
+		.. seealso::	:ref:`health-proto`
+
+	:tcpPort: The port on which this server listens for incoming TCP connections
+
+		.. note::	This is typically thought of as synonymous with "HTTP port", as the port specified by ``httpsPort`` may also be used for incoming TCP connections.
+
+	:type:			The name of the 'type' of this server
+	:xmppId:		An identifier to be used in XMPP communications with the server - in nearly all cases this will be the same as ``hostName``
+	:xmppPasswd:		The password used in XMPP communications with the server
+
+:size:		The page number - if pagination was requested in the query parameters, else ``0`` to indicate no pagination - of the results represented by the ``response`` array. This is named "size" for legacy reasons
+
+.. 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, Set-Cookie, Cookie
+	Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+	Access-Control-Allow-Origin: *
+	Content-Encoding: gzip
+	Content-Type: application/json
+	Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 24 Feb 2020 01:27:36 GMT; Max-Age=3600; HttpOnly
+	Whole-Content-Sha512: HW2F3CEpohNAvNlEDhUfXmtwpEka4dwUWFVUSSjW98aXiv10vI6ysRIcC2P9huabCz5fdHqY3tp0LR4ekwEHqw==
+	X-Server-Name: traffic_ops_golang/
+	Date: Mon, 24 Feb 2020 00:27:36 GMT
+	Content-Length: 493
+
+	{
+		"limit": 1000,
+		"orderby": "hostName",
+		"response": [
+			{
+				"cachegroup": "CDN_in_a_Box_Edge",
+				"cdnName": "CDN-in-a-Box",
+				"deliveryservices": [
+					1
+				],
+				"domainName": "infra.ciab.test",
+				"guid": null,
+				"hardwareInfo": null,
+				"hostName": "edge",
+				"httpsPort": 443,
+				"id": 5,
+				"iloIpAddress": "",
+				"iloIpGateway": "",
+				"iloIpNetmask": "",
+				"iloPassword": "",
+				"iloUsername": "",
+				"interfaceMtu": 1500,
+				"interfaceName": "eth0",
+				"ip6Address": "fc01:9400:1000:8::3",
+				"ip6Gateway": "fc01:9400:1000:8::1",
+				"ipAddress": "172.16.239.3",
+				"ipGateway": "172.16.239.1",
+				"ipNetmask": "255.255.255.0",
+				"mgmtIpAddress": "",
+				"mgmtIpGateway": "",
+				"mgmtIpNetmask": "",
+				"offlineReason": "",
+				"physLocation": "Apachecon North America 2018",
+				"profile": "ATS_EDGE_TIER_CACHE",
+				"profileDesc": "Edge Cache - Apache Traffic Server",
+				"rack": "",
+				"routerHostName": "",
+				"routerPortName": "",
+				"status": "REPORTED",
+				"tcpPort": 80,
+				"type": "EDGE",
+				"xmppId": "edge",
+				"xmppPasswd": ""
+			}
+		],
+		"size": 1
+	}
+
+.. [1] For more information see the `Wikipedia page on Lights-Out management <https://en.wikipedia.org/wiki/Out-of-band_management>`_\ .

traffic_control/clients/python/trafficops/tosession.py

@@ -1642,16 +1642,6 @@ def get_server_delivery_services(self, server_id=None):
 		:raises: Union[LoginError, OperationError]
 		"""
 
-	@api_request('get', 'servers/hostname/{name}/details', ('2.0',))
-	def get_server_details(self, name=None):
-		"""
-		Get server details from trafficOps
-		:ref:`to-api-servers-hostname-name-details`
-		:param hostname: Server hostname
-		:rtype: Tuple[Union[Dict[str, Any], List[Dict[str, Any]]], requests.Response]
-		:raises: Union[LoginError, OperationError]
-		"""
-
 	@api_request('post', 'servercheck', ('2.0',))
 	def create_servercheck(self, data=None):
 		"""

traffic_ops/traffic_ops_golang/routing/routes.go

@@ -299,7 +299,6 @@ func Routes(d ServerData) ([]Route, []RawRoute, http.Handler, error) {
 
 		//Server Details
 		{api.Version{2, 0}, http.MethodGet, `servers/details/?$`, server.GetDetailParamHandler, auth.PrivLevelReadOnly, Authenticated, nil, 2261264714, noPerlBypass},
-		{api.Version{2, 0}, http.MethodGet, `servers/hostname/{hostName}/details/?$`, server.GetDetailHandler, auth.PrivLevelReadOnly, Authenticated, nil, 272366128, noPerlBypass},
 
 		//Server status
 		{api.Version{2, 0}, http.MethodPut, `servers/{id}/status$`, server.UpdateStatusHandler, auth.PrivLevelOperations, Authenticated, nil, 276663851, noPerlBypass},

traffic_ops/traffic_ops_golang/server/detail.go

@@ -34,24 +34,26 @@ import (
 )
 
 func GetDetailHandler(w http.ResponseWriter, r *http.Request) {
+	alt := "GET servers/details with query parameters hostName"
 	inf, userErr, sysErr, errCode := api.NewInfo(r, nil, nil)
 	if userErr != nil || sysErr != nil {
-		api.HandleErr(w, r, inf.Tx.Tx, errCode, userErr, sysErr)
+		api.HandleDeprecatedErr(w, r, inf.Tx.Tx, errCode, userErr, sysErr, &alt)
 		return
 	}
 	defer inf.Close()
 
 	servers, err := getDetailServers(inf.Tx.Tx, inf.User, inf.Params["hostName"], -1, "", 0)
 	if err != nil {
-		api.HandleErr(w, r, inf.Tx.Tx, http.StatusInternalServerError, nil, errors.New("getting detail servers: "+err.Error()))
+		api.HandleDeprecatedErr(w, r, inf.Tx.Tx, http.StatusInternalServerError, nil, errors.New("getting detail servers: "+err.Error()), &alt)
 		return
 	}
 	if len(servers) == 0 {
-		api.HandleErr(w, r, inf.Tx.Tx, http.StatusNotFound, nil, nil)
+		api.HandleDeprecatedErr(w, r, inf.Tx.Tx, http.StatusNotFound, nil, nil, &alt)
 		return
 	}
 	server := servers[0]
-	api.WriteResp(w, r, server)
+	alerts := api.CreateDeprecationAlerts(&alt)
+	api.WriteAlertsObj(w, r, http.StatusOK, alerts, server)
 }
 
 func GetDetailParamHandler(w http.ResponseWriter, r *http.Request) {