Skip to content
This repository was archived by the owner on Nov 24, 2025. It is now read-only.

Deprecate /capabilities/{{name}} #3880

Merged
rawlinp merged 4 commits into from
Jan 30, 2020
Merged

Deprecate /capabilities/{{name}} #3880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
76f0635
Added deprecation notices to endpoint responses
ocket8888 Jan 29, 2020
e02aaaa
Added deprecation notices to docs, updated examples
ocket8888 Jan 29, 2020
a2d35d3
Changed helper name to reduce collisions
ocket8888 Jan 30, 2020
18150f6
Fixed misspelled 'parameter' as 'paramter'
ocket8888 Jan 30, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 72 additions & 26 deletions docs/source/api/capabilities_name.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
------------------
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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"
}
]}

28 changes: 15 additions & 13 deletions traffic_ops/app/lib/API/Capability.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ) {
Expand All @@ -60,7 +62,7 @@ sub name {
}
);
}
$self->success( \@data );
$self->deprecation(200, $alt, \@data );
}

sub create {
Expand Down Expand Up @@ -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 };
Expand All @@ -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);
}
}

Expand All @@ -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);
}
}

Expand Down
19 changes: 19 additions & 0 deletions traffic_ops/app/lib/MojoPlugins/Response.pm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down