diff --git a/docs/source/api/capabilities_name.rst b/docs/source/api/capabilities_name.rst index f82c186810..9ece17798b 100644 --- a/docs/source/api/capabilities_name.rst +++ b/docs/source/api/capabilities_name.rst @@ -18,9 +18,14 @@ ************************* ``capabilities/{{name}}`` ************************* +.. deprecated:: ATCv4 + As of ATC version 4.0, every method of this endpoint is deprecated. See each method for details. ``GET`` ======= +.. deprecated:: ATCv4 + This method of this endpoint is deprecated, please use the 'name' parameter of a ``GET`` request to :ref:`to-api-capabilities` instead. + Get a capability by name. :Auth. Required: Yes @@ -37,6 +42,16 @@ Request Structure | name | The name of the capability of interest | +------+----------------------------------------+ +.. code-block:: http + :caption: Request Example + + GET /api/1.5/capabilities/testquest HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate + Accept: */* + Connection: keep-alive + Cookie: mojolicious=... + Response Structure ------------------ :description: Describes the APIs covered by the capability @@ -52,25 +67,34 @@ Response Structure 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-Encoding: gzip + Content-Length: 221 Content-Type: application/json - Date: Wed, 14 Nov 2018 20:37:17 GMT + Date: Wed, 29 Jan 2020 20:49:49 GMT Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; expires=Thu, 30 Jan 2020 00:49:49 GMT; path=/; HttpOnly Vary: Accept-Encoding - Whole-Content-Sha512: 0YBTC5TEAOJ6B8gsaKgOD1ni2hnZ8Kh9u2JhcmExoGIPaMEKpp4Omr4FglkOQZuh/IB90eJjBMNMeCEvZCxWRg== - Content-Length: 167 - { "response": [ + { "alerts": [ + { + "level": "warning", + "text": "This endpoint is deprecated, please use 'GET /capabilities with the 'name' query parameter' instead" + } + ], + "response": [ { - "lastUpdated": "2018-11-14 20:33:00.275376+00", - "name": "test", - "description": "This is only a test. If this were a real capability, it might do something" + "lastUpdated": "2020-01-29 20:10:53.821978+00", + "name": "testquest", + "description": "A test capability for API examples" } ]} ``PUT`` ======= +.. deprecated:: ATCv4 + This method of this endpoint is deprecated. In the future, Capabilities will be immutable, and so no alternative is offered. + Edit a capability. :Auth. Required: Yes @@ -92,15 +116,15 @@ Request Structure .. code-block:: http :caption: Request Example - PUT /api/1.4/capabilities/test HTTP/1.1 - Host: trafficops.infra.ciab.test - User-Agent: curl/7.47.0 + PUT /api/1.5/capabilities/testquest HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate Accept: */* + Connection: keep-alive Cookie: mojolicious=... - Content-Length: 45 - Content-Type: application/json + Content-Length: 36 - {"description": "A much shorter description"} + {"description": "A new description"} Response Structure ------------------ @@ -117,29 +141,36 @@ Response Structure 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-Encoding: gzip + Content-Length: 224 Content-Type: application/json - Date: Wed, 14 Nov 2018 20:40:33 GMT + Date: Wed, 29 Jan 2020 21:25:10 GMT Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; expires=Thu, 30 Jan 2020 01:25:10 GMT; path=/; HttpOnly Vary: Accept-Encoding - Whole-Content-Sha512: +5mLZ/CJnDkJMbnFviXtVdjwt4bu7ykiMIs73zsnuKV/k4q/d025b2pjYDQkSgtfWPJ73FcusAuBM9TCVT3KsA== - Content-Length: 181 { "alerts": [ { "level": "success", "text": "Capability was updated." + }, + { + "level": "warning", + "text": "This endpoint and its functionality is deprecated, and will be removed in the future" } ], "response": { - "lastUpdated": "2018-11-14 20:33:00.275376+00", - "name": "test", - "description": "A much shorter description" + "lastUpdated": "2020-01-29 21:24:56.361518+00", + "name": "testquest", + "description": "A new description" }} ``DELETE`` ========== +.. deprecated:: ATCv4 + This method of this endpoint is deprecated. In the future, Capabilities will be immutable, and so no alternative is offered. + Delete a capability. :Auth. Required: Yes @@ -156,6 +187,18 @@ Request Structure | ``name`` | yes | Capability name. | +-----------------+----------+------------------------------------------------+ +.. code-block:: http + :caption: Request Example + + DELETE /api/1.5/capabilities/testquest HTTP/1.1 + User-Agent: python-requests/2.22.0 + Accept-Encoding: gzip, deflate + Accept: */* + Connection: keep-alive + Cookie: mojolicious=... + Content-Length: 0 + + Response Structure ------------------ .. code-block:: http @@ -167,18 +210,21 @@ Response Structure 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-Encoding: gzip + Content-Length: 146 Content-Type: application/json - Date: Wed, 14 Nov 2018 20:45:37 GMT + Date: Wed, 29 Jan 2020 21:27:57 GMT Server: Mojolicious (Perl) - Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly + Set-Cookie: mojolicious=...; expires=Thu, 30 Jan 2020 01:27:57 GMT; path=/; HttpOnly Vary: Accept-Encoding - Whole-Content-Sha512: IlAiV4ebwTpMIgeYlR5RuwOhwmHsFs8Ekt7AaEDb3v+lXjvjkqU98xFsfNWvpvPbT/iJnotENhtVq8TVdvoPLg== - Content-Length: 61 { "alerts": [ { "level": "success", "text": "Capability deleted." + }, + { + "level": "warning", + "text": "This endpoint and its functionality is deprecated, and will be removed in the future" } ]} - diff --git a/traffic_ops/app/lib/API/Capability.pm b/traffic_ops/app/lib/API/Capability.pm index 53d9b47309..4019fd5875 100644 --- a/traffic_ops/app/lib/API/Capability.pm +++ b/traffic_ops/app/lib/API/Capability.pm @@ -46,9 +46,11 @@ sub name { my $self = shift; my $name = $self->param('name'); + my $alt = "GET /capabilities with the 'name' query parameter"; + my $rs_data = $self->db->resultset("Capability")->search( 'me.name' => $name ); if ( !defined($rs_data) ) { - return $self->not_found(); + return $self->with_deprecation("Resource not found.", "error", 404, $alt); } my @data = (); while ( my $row = $rs_data->next ) { @@ -60,7 +62,7 @@ sub name { } ); } - $self->success( \@data ); + $self->deprecation(200, $alt, \@data ); } sub create { @@ -119,22 +121,22 @@ sub update { my $params = $self->req->json; if ( !&is_oper($self) ) { - return $self->forbidden(); + return $self->with_deprecation_with_no_alternative("Forbidden", "error", 403); } if ( !defined($params) ) { - return $self->alert("Parameters must be in JSON format."); + return $self->with_deprecation_with_no_alternative("Parameters must be in JSON format.", "error", 400); } my $description = $params->{description} if defined( $params->{description} ); my $capability = $self->db->resultset('Capability')->find( { name => $name } ); if ( !defined($capability) ) { - return $self->not_found(); + return $self->with_deprecation_with_no_alternative("Resource not found.", "error", 404); } if ( !defined($description) or $description eq "" ) { - return $self->alert("Description is required."); + return $self->with_deprecation_with_no_alternative("Description is required.", "error", 400); } my $values = { description => $description }; @@ -148,10 +150,10 @@ sub update { &log( $self, "Updated Capability: '$response->{name}', '$response->{description}'", "APICHANGE" ); - return $self->success( $response, "Capability was updated." ); + return $self->with_deprecation_with_no_alternative("Capability was updated.", "success", 200, $response); } else { - return $self->alert("Capability update failed."); + return $self->with_deprecation_with_no_alternative("Capability update failed.", "error", 400); } } @@ -160,27 +162,27 @@ sub delete { my $name = $self->param('name'); if ( !&is_oper($self) ) { - return $self->forbidden(); + return $self->with_deprecation_with_no_alternative("Forbidden", "error", 403); } my $capability = $self->db->resultset('Capability')->find( { name => $name } ); if ( !defined($capability) ) { - return $self->not_found(); + return $self->with_deprecation_with_no_alternative("Resource not found.", "error", 404); } # make sure no api_capability refers to this capability my $rs_data = $self->db->resultset("ApiCapability")->find( { 'me.capability' => $name } ); if ( defined($rs_data) ) { my $reference_id = $rs_data->id; - return $self->alert("Capability \'$name\' is refered by an api_capability mapping: $reference_id. Deletion failed."); + return $self->with_deprecation_with_no_alternative("Capability \'$name\' is refered by an api_capability mapping: $reference_id. Deletion failed.", "error", 400); } my $rs = $capability->delete(); if ($rs) { - return $self->success_message("Capability deleted."); + return $self->with_deprecation_with_no_alternative("Capability deleted.", "success", 200); } else { - return $self->alert("Capability deletion failed."); + return $self->with_deprecation_with_no_alternative("Capability deletion failed.", "error", 400); } } diff --git a/traffic_ops/app/lib/MojoPlugins/Response.pm b/traffic_ops/app/lib/MojoPlugins/Response.pm index d636ab5fb4..6dcd75d8bb 100644 --- a/traffic_ops/app/lib/MojoPlugins/Response.pm +++ b/traffic_ops/app/lib/MojoPlugins/Response.pm @@ -187,6 +187,25 @@ sub register { } ); + $app->renderer->add_helper( + with_deprecation_with_no_alternative => sub { + my $self = shift || confess("Call on an instance of MojoPlugins::Response"); + my $alert = shift || confess("Please supply an alert string"); + my $level = shift || confess("Please supply an alert level such as 'error' or 'warning'"); + my $code = shift || confess("Please supply a response code e.g. 400"); + my $response_object = shift; + + my $builder ||= MojoPlugins::Response::Builder->new($self, @_); + my @alerts_response = ({$LEVEL_KEY => $level, $TEXT_KEY => $alert}, {$LEVEL_KEY => $WARNING_LEVEL, $TEXT_KEY => "This endpoint and its functionality is deprecated, and will be removed in the future"}); + + if (defined($response_object)) { + return $self->render( $STATUS_KEY => $code, $JSON_KEY => { $ALERTS_KEY => \@alerts_response, $RESPONSE_KEY => $response_object } ); + } else { + return $self->render( $STATUS_KEY => $code, $JSON_KEY => { $ALERTS_KEY => \@alerts_response } ); + } + } + ); + # Alerts (500) $app->renderer->add_helper( internal_server_error => sub {