From d7c02a89ea2597d6acbb82921bcad3f198149834 Mon Sep 17 00:00:00 2001 From: Tomas Cohen Arazi Date: Wed, 29 Jul 2020 16:10:47 -0300 Subject: [PATCH] Bug 22343: API routes for SMTP servers CRUD --- Koha/REST/V1/Config/SMTP/Servers.pm | 194 +++++++++++ api/v1/swagger/definitions.json | 3 + api/v1/swagger/definitions/smtp_server.json | 66 ++++ api/v1/swagger/parameters.json | 3 + api/v1/swagger/parameters/smtp_server.json | 9 + api/v1/swagger/paths.json | 6 + api/v1/swagger/paths/config_smtp_servers.json | 319 ++++++++++++++++++ 7 files changed, 600 insertions(+) create mode 100644 Koha/REST/V1/Config/SMTP/Servers.pm create mode 100644 api/v1/swagger/definitions/smtp_server.json create mode 100644 api/v1/swagger/parameters/smtp_server.json create mode 100644 api/v1/swagger/paths/config_smtp_servers.json diff --git a/Koha/REST/V1/Config/SMTP/Servers.pm b/Koha/REST/V1/Config/SMTP/Servers.pm new file mode 100644 index 0000000000..2144265456 --- /dev/null +++ b/Koha/REST/V1/Config/SMTP/Servers.pm @@ -0,0 +1,194 @@ +package Koha::REST::V1::Config::SMTP::Servers; + +# This file is part of Koha. +# +# Koha is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# Koha is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Koha; if not, see . + +use Modern::Perl; + +use Mojo::Base 'Mojolicious::Controller'; + +use Koha::SMTP::Servers; + +use Try::Tiny; + +=head1 API + +=head2 Methods + +=head3 list + +Controller method that handles listing Koha::SMTP::Server objects + +=cut + +sub list { + my $c = shift->openapi->valid_input or return; + + return try { + my $smtp_servers_set = Koha::SMTP::Servers->new; + my $smtp_servers = $c->objects->search( $smtp_servers_set ); + return $c->render( + status => 200, + openapi => $smtp_servers + ); + } + catch { + $c->unhandled_exception($_); + }; +} + +=head3 get + +Controller method that handles retrieving a single Koha::SMTP::Server object + +=cut + +sub get { + my $c = shift->openapi->valid_input or return; + + return try { + my $smtp_server = Koha::SMTP::Servers->find( $c->validation->param('smtp_server_id') ); + + unless ($smtp_server) { + return $c->render( + status => 404, + openapi => { + error => "SMTP server not found" + } + ); + } + + my $embed = $c->stash('koha.embed'); + + return $c->render( + status => 200, + openapi => $smtp_server->to_api({ embed => $embed }) + ); + } + catch { + $c->unhandled_exception($_); + } +} + +=head3 add + +Controller method that handles adding a new Koha::SMTP::Server object + +=cut + +sub add { + my $c = shift->openapi->valid_input or return; + + return try { + + my $smtp_server = Koha::SMTP::Server->new_from_api( $c->validation->param('body') ); + $smtp_server->store; + + $c->res->headers->location( $c->req->url->to_string . '/' . $smtp_server->id ); + + return $c->render( + status => 201, + openapi => $smtp_server->to_api + ); + } + catch { + if ( blessed $_ and $_->isa('Koha::Exceptions::Object::DuplicateID') ) { + return $c->render( + status => 409, + openapi => { + error => $_->error, + conflict => $_->duplicate_id + } + ); + } + + $c->unhandled_exception($_); + }; +} + +=head3 update + +Controller method that handles updating a Koha::SMTP::Server object + +=cut + +sub update { + my $c = shift->openapi->valid_input or return; + + my $smtp_server = Koha::SMTP::Servers->find( $c->validation->param('smtp_server_id') ); + + if ( not defined $smtp_server ) { + return $c->render( + status => 404, + openapi => { + error => "Object not found" + } + ); + } + + return try { + $smtp_server->set_from_api( $c->validation->param('body') ); + $smtp_server->store->discard_changes; + + return $c->render( + status => 200, + openapi => $smtp_server->to_api + ); + } + catch { + if ( blessed $_ and $_->isa('Koha::Exceptions::Object::DuplicateID') ) { + return $c->render( + status => 409, + openapi => { + error => $_->error, + conflict => $_->duplicate_id + } + ); + } + + $c->unhandled_exception($_); + }; +} + +=head3 delete + +Controller method that handles deleting a Koha::SMTP::Server object + +=cut + +sub delete { + my $c = shift->openapi->valid_input or return; + + my $smtp_server = Koha::SMTP::Servers->find( $c->validation->param('smtp_server_id') ); + + if ( not defined $smtp_server ) { + return $c->render( status => 404, + openapi => { error => "Object not found" } ); + } + + return try { + $smtp_server->delete; + + return $c->render( + status => 204, + openapi => q{} + ); + } + catch { + $c->unhandled_exception($_); + }; +} + +1; diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json index 716e8703b6..61e6c15306 100644 --- a/api/v1/swagger/definitions.json +++ b/api/v1/swagger/definitions.json @@ -67,5 +67,8 @@ }, "return_claim": { "$ref": "definitions/return_claim.json" + }, + "smtp_server": { + "$ref": "definitions/smtp_server.json" } } diff --git a/api/v1/swagger/definitions/smtp_server.json b/api/v1/swagger/definitions/smtp_server.json new file mode 100644 index 0000000000..7c36ebed24 --- /dev/null +++ b/api/v1/swagger/definitions/smtp_server.json @@ -0,0 +1,66 @@ +{ + "type": "object", + "properties": { + "smtp_server_id": { + "type": "integer", + "description": "Internal SMTP server identifier" + }, + "name": { + "type": "string", + "description": "Name of the SMTP server" + }, + "library_id": { + "type": [ + "string", + "null" + ], + "description": "Internal identifier for the library using it. null means global" + }, + "host": { + "type": "string", + "description": "SMTP host name" + }, + "port": { + "type": "integer", + "description": "TCP port number" + }, + "timeout": { + "type": "integer", + "description": "Maximum time in seconds to wait for server" + }, + "ssl_mode": { + "type": "string", + "enum": [ + "disabled", + "ssl", + "starttls" + ], + "description": "If SSL/TLS will be used" + }, + "user_name": { + "type": [ + "string", + "null" + ], + "description": "The user name to use for authentication (optional)" + }, + "password": { + "type": [ + "string", + "null" + ], + "description": "The password to use for authentication (optional)" + }, + "debug": { + "type": "boolean", + "description": "If the SMTP connection is set to debug mode" + }, + "library": { + "type": [ + "object", + "null" + ], + "description": "Embedded library object (x-koha-embed)" + } + } +} diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json index cab2d53b47..a39a439ad7 100644 --- a/api/v1/swagger/parameters.json +++ b/api/v1/swagger/parameters.json @@ -29,6 +29,9 @@ "order_id_pp": { "$ref": "parameters/order.json#/order_id_pp" }, + "smtp_server_id_pp": { + "$ref": "parameters/smtp_server.json#/smtp_server_id_pp" + }, "vendoridPathParam": { "$ref": "parameters/vendor.json#/vendoridPathParam" }, diff --git a/api/v1/swagger/parameters/smtp_server.json b/api/v1/swagger/parameters/smtp_server.json new file mode 100644 index 0000000000..3ba00b4d82 --- /dev/null +++ b/api/v1/swagger/parameters/smtp_server.json @@ -0,0 +1,9 @@ +{ + "smtp_server_id_pp": { + "name": "smtp_server_id", + "in": "path", + "description": "SMTP server internal identifier", + "required": true, + "type": "integer" + } +} diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json index 8f1af595ce..8ba95189dc 100644 --- a/api/v1/swagger/paths.json +++ b/api/v1/swagger/paths.json @@ -41,6 +41,12 @@ "/clubs/{club_id}/holds": { "$ref": "paths/clubs.json#/~1clubs~1{club_id}~1holds" }, + "/config/smtp_servers": { + "$ref": "paths/config_smtp_servers.json#/~1config~1smtp_servers" + }, + "/config/smtp_servers/{smtp_server_id}": { + "$ref": "paths/config_smtp_servers.json#/~1config~1smtp_servers~1{smtp_server_id}" + }, "/holds": { "$ref": "paths/holds.json#/~1holds" }, diff --git a/api/v1/swagger/paths/config_smtp_servers.json b/api/v1/swagger/paths/config_smtp_servers.json new file mode 100644 index 0000000000..66d469394e --- /dev/null +++ b/api/v1/swagger/paths/config_smtp_servers.json @@ -0,0 +1,319 @@ +{ + "/config/smtp_servers": { + "get": { + "x-mojo-to": "Config::SMTP::Servers#list", + "operationId": "listSMTPServers", + "tags": [ + "config", + "smtp" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "$ref": "../parameters.json#/match" + }, + { + "$ref": "../parameters.json#/order_by" + }, + { + "$ref": "../parameters.json#/page" + }, + { + "$ref": "../parameters.json#/per_page" + }, + { + "$ref": "../parameters.json#/q_param" + }, + { + "$ref": "../parameters.json#/q_body" + }, + { + "$ref": "../parameters.json#/q_header" + } + ], + "responses": { + "200": { + "description": "A list of SMTP servers", + "schema": { + "type": "array", + "items": { + "$ref": "../definitions.json#/smtp_server" + } + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "parameters": "1" + } + }, + "x-koha-embed": [ + "library" + ] + }, + "post": { + "x-mojo-to": "Config::SMTP::Servers#add", + "operationId": "addSMTPServer", + "tags": [ + "config", + "smtp" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "description": "A JSON object representing a new SMTP server configuration", + "required": true, + "schema": { + "$ref": "../definitions.json#/smtp_server" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "An SMTP server object", + "schema": { + "$ref": "../definitions.json#/smtp_server" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "409": { + "description": "Conflict in creating resource", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "parameters": "1" + } + } + } + }, + "/config/smtp_servers/{smtp_server_id}": { + "get": { + "x-mojo-to": "Config::SMTP::Servers#get", + "operationId": "getSMTPServer", + "tags": [ + "config", + "smtp" + ], + "parameters": [ + { + "$ref": "../parameters.json#/smtp_server_id_pp" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "An SMTP server object", + "schema": { + "$ref": "../definitions.json#/smtp_server" + } + }, + "404": { + "description": "Object not found", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "409": { + "description": "Conflict updating resource", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "parameters": "1" + } + } + }, + "put": { + "x-mojo-to": "Config::SMTP::Servers#update", + "operationId": "updateSMTPServer", + "tags": [ + "config", + "smtp" + ], + "parameters": [ + { + "$ref": "../parameters.json#/smtp_server_id_pp" + }, + { + "name": "body", + "in": "body", + "description": "An SMTP server object", + "required": true, + "schema": { + "$ref": "../definitions.json#/smtp_server" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "An SMTP server object", + "schema": { + "$ref": "../definitions.json#/smtp_server" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Object not found", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "parameters": "1" + } + } + }, + "delete": { + "x-mojo-to": "Config::SMTP::Servers#delete", + "operationId": "deleteSMTPServer", + "tags": [ + "config", + "smtp" + ], + "parameters": [ + { + "$ref": "../parameters.json#/smtp_server_id_pp" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "SMTP server deleted" + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Access forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "404": { + "description": "Object not found", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal error", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "503": { + "description": "Under maintenance", + "schema": { + "$ref": "../definitions.json#/error" + } + } + }, + "x-koha-authorization": { + "permissions": { + "parameters": "1" + } + } + } + } +} -- 2.28.0