Browse Source

Bug 22343: API routes for SMTP servers CRUD

This patch introduces API routes for handling SMTP servers.

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
20.11.x
Tomas Cohen Arazi 2 years ago
committed by Jonathan Druart
parent
commit
95aa8fc64b
  1. 194
      Koha/REST/V1/Config/SMTP/Servers.pm
  2. 3
      api/v1/swagger/definitions.json
  3. 57
      api/v1/swagger/definitions/smtp_server.json
  4. 3
      api/v1/swagger/parameters.json
  5. 9
      api/v1/swagger/parameters/smtp_server.json
  6. 6
      api/v1/swagger/paths.json
  7. 316
      api/v1/swagger/paths/config_smtp_servers.json
  8. 358
      t/db_dependent/api/v1/smtp_servers.t

194
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 <http://www.gnu.org/licenses>.
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->discard_changes;
$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;

3
api/v1/swagger/definitions.json

@ -67,5 +67,8 @@
},
"return_claim": {
"$ref": "definitions/return_claim.json"
},
"smtp_server": {
"$ref": "definitions/smtp_server.json"
}
}

57
api/v1/swagger/definitions/smtp_server.json

@ -0,0 +1,57 @@
{
"type": "object",
"properties": {
"smtp_server_id": {
"type": "integer",
"description": "Internal SMTP server identifier",
"readOnly": true
},
"name": {
"type": "string",
"description": "Name of the SMTP server"
},
"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"
}
},
"additionalProperties": false,
"required": [
"name"
]
}

3
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"
},

9
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"
}
}

6
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"
},

316
api/v1/swagger/paths/config_smtp_servers.json

@ -0,0 +1,316 @@
{
"/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": "manage_smtp_servers"
}
}
},
"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": "manage_smtp_servers"
}
}
}
},
"/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": "manage_smtp_servers"
}
}
},
"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": "manage_smtp_servers"
}
}
},
"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": "manage_smtp_servers"
}
}
}
}
}

358
t/db_dependent/api/v1/smtp_servers.t

@ -0,0 +1,358 @@
#!/usr/bin/env perl
# 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 <http://www.gnu.org/licenses>.
use Modern::Perl;
use Test::More tests => 5;
use Test::Mojo;
use t::lib::TestBuilder;
use t::lib::Mocks;
use Koha::SMTP::Servers;
use Koha::Database;
my $schema = Koha::Database->new->schema;
my $builder = t::lib::TestBuilder->new;
my $t = Test::Mojo->new('Koha::REST::V1');
t::lib::Mocks::mock_preference( 'RESTBasicAuth', 1 );
subtest 'list() tests' => sub {
plan tests => 11;
$schema->storage->txn_begin;
Koha::SMTP::Servers->search->delete;
my $librarian = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 3**2 } # parameters flag = 3
}
);
my $password = 'thePassword123';
$librarian->set_password( { password => $password, skip_validation => 1 } );
my $userid = $librarian->userid;
my $patron = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 0 }
}
);
$patron->set_password( { password => $password, skip_validation => 1 } );
my $unauth_userid = $patron->userid;
## Authorized user tests
# No SMTP servers, so empty array should be returned
$t->get_ok("//$userid:$password@/api/v1/config/smtp_servers")
->status_is(200)->json_is( [] );
my $smtp_server =
$builder->build_object( { class => 'Koha::SMTP::Servers' } );
# One city created, should get returned
$t->get_ok("//$userid:$password@/api/v1/config/smtp_servers")
->status_is(200)->json_is( [ $smtp_server->to_api ] );
my $another_smtp_server =
$builder->build_object( { class => 'Koha::SMTP::Servers' } );
# Two SMTP servers created, they should both be returned
$t->get_ok("//$userid:$password@/api/v1/config/smtp_servers")
->status_is(200)
->json_is( [ $smtp_server->to_api, $another_smtp_server->to_api, ] );
# Unauthorized access
$t->get_ok("//$unauth_userid:$password@/api/v1/config/smtp_servers")
->status_is(403);
$schema->storage->txn_rollback;
};
subtest 'get() tests' => sub {
plan tests => 8;
$schema->storage->txn_begin;
my $smtp_server =
$builder->build_object( { class => 'Koha::SMTP::Servers' } );
my $librarian = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 3**2 } # parameters flag = 3
}
);
my $password = 'thePassword123';
$librarian->set_password( { password => $password, skip_validation => 1 } );
my $userid = $librarian->userid;
my $patron = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 0 }
}
);
$patron->set_password( { password => $password, skip_validation => 1 } );
my $unauth_userid = $patron->userid;
$t->get_ok(
"//$userid:$password@/api/v1/config/smtp_servers/" . $smtp_server->id )
->status_is(200)->json_is( $smtp_server->to_api );
$t->get_ok( "//$unauth_userid:$password@/api/v1/config/smtp_servers/"
. $smtp_server->id )->status_is(403);
my $smtp_server_to_delete =
$builder->build_object( { class => 'Koha::SMTP::Servers' } );
my $non_existent_id = $smtp_server_to_delete->id;
$smtp_server_to_delete->delete;
$t->get_ok(
"//$userid:$password@/api/v1/config/smtp_servers/$non_existent_id")
->status_is(404)->json_is( '/error' => 'SMTP server not found' );
$schema->storage->txn_rollback;
};
subtest 'add() tests' => sub {
plan tests => 18;
$schema->storage->txn_begin;
Koha::SMTP::Servers->search->delete;
my $librarian = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 3**2 } # parameters flag = 3
}
);
my $password = 'thePassword123';
$librarian->set_password( { password => $password, skip_validation => 1 } );
my $userid = $librarian->userid;
my $patron = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 0 }
}
);
$patron->set_password( { password => $password, skip_validation => 1 } );
my $unauth_userid = $patron->userid;
my $smtp_server =
$builder->build_object( { class => 'Koha::SMTP::Servers' } );
my $smtp_server_data = $smtp_server->to_api;
delete $smtp_server_data->{smtp_server_id};
$smtp_server->delete;
# Unauthorized attempt to write
$t->post_ok(
"//$unauth_userid:$password@/api/v1/config/smtp_servers" => json =>
$smtp_server_data )->status_is(403);
# Authorized attempt to write invalid data
my $smtp_server_with_invalid_field = {
name => 'Some other server',
blah => 'blah'
};
$t->post_ok( "//$userid:$password@/api/v1/config/smtp_servers" => json =>
$smtp_server_with_invalid_field )->status_is(400)->json_is(
"/errors" => [
{
message => "Properties not allowed: blah.",
path => "/body"
}
]
);
# Authorized attempt to write
my $smtp_server_id =
$t->post_ok( "//$userid:$password@/api/v1/config/smtp_servers" => json =>
$smtp_server_data )->status_is( 201, 'SWAGGER3.2.1' )->header_like(
Location => qr|^\/api\/v1\/config\/smtp_servers\/\d*|,
'SWAGGER3.4.1'
)->json_is( '/name' => $smtp_server_data->{name} )
->json_is( '/state' => $smtp_server_data->{state} )
->json_is( '/postal_code' => $smtp_server_data->{postal_code} )
->json_is( '/country' => $smtp_server_data->{country} )
->tx->res->json->{smtp_server_id};
# Authorized attempt to create with null id
$smtp_server_data->{smtp_server_id} = undef;
$t->post_ok( "//$userid:$password@/api/v1/config/smtp_servers" => json =>
$smtp_server_data )->status_is(400)->json_has('/errors');
# Authorized attempt to create with existing id
$smtp_server_data->{smtp_server_id} = $smtp_server_id;
$t->post_ok( "//$userid:$password@/api/v1/config/smtp_servers" => json =>
$smtp_server_data )->status_is(400)->json_is(
"/errors" => [
{
message => "Read-only.",
path => "/body/smtp_server_id"
}
]
);
$schema->storage->txn_rollback;
};
subtest 'update() tests' => sub {
plan tests => 15;
$schema->storage->txn_begin;
my $librarian = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 3**2 } # parameters flag = 3
}
);
my $password = 'thePassword123';
$librarian->set_password( { password => $password, skip_validation => 1 } );
my $userid = $librarian->userid;
my $patron = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 0 }
}
);
$patron->set_password( { password => $password, skip_validation => 1 } );
my $unauth_userid = $patron->userid;
my $smtp_server_id =
$builder->build_object( { class => 'Koha::SMTP::Servers' } )->id;
# Unauthorized attempt to update
$t->put_ok(
"//$unauth_userid:$password@/api/v1/config/smtp_servers/$smtp_server_id"
=> json => { name => 'New unauthorized name change' } )
->status_is(403);
# Attempt partial update on a PUT
my $smtp_server_with_missing_field = {
host => 'localhost',
ssl_mode => 'disabled'
};
$t->put_ok(
"//$userid:$password@/api/v1/config/smtp_servers/$smtp_server_id" =>
json => $smtp_server_with_missing_field )->status_is(400)
->json_is( "/errors" =>
[ { message => "Missing property.", path => "/body/name" } ] );
# Full object update on PUT
my $smtp_server_with_updated_field = { name => "Some name", };
$t->put_ok(
"//$userid:$password@/api/v1/config/smtp_servers/$smtp_server_id" =>
json => $smtp_server_with_updated_field )->status_is(200)
->json_is( '/name' => 'Some name' );
# Authorized attempt to write invalid data
my $smtp_server_with_invalid_field = {
blah => "Blah",
name => 'Some name'
};
$t->put_ok(
"//$userid:$password@/api/v1/config/smtp_servers/$smtp_server_id" =>
json => $smtp_server_with_invalid_field )->status_is(400)->json_is(
"/errors" => [
{
message => "Properties not allowed: blah.",
path => "/body"
}
]
);
my $smtp_server_to_delete =
$builder->build_object( { class => 'Koha::SMTP::Servers' } );
my $non_existent_id = $smtp_server_to_delete->id;
$smtp_server_to_delete->delete;
$t->put_ok(
"//$userid:$password@/api/v1/config/smtp_servers/$non_existent_id" =>
json => $smtp_server_with_updated_field )->status_is(404);
# Wrong method (POST)
$smtp_server_with_updated_field->{smtp_server_id} = 2;
$t->post_ok(
"//$userid:$password@/api/v1/config/smtp_servers/$smtp_server_id" =>
json => $smtp_server_with_updated_field )->status_is(404);
$schema->storage->txn_rollback;
};
subtest 'delete() tests' => sub {
plan tests => 7;
$schema->storage->txn_begin;
my $librarian = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 3**2 } # parameters flag = 3
}
);
my $password = 'thePassword123';
$librarian->set_password( { password => $password, skip_validation => 1 } );
my $userid = $librarian->userid;
my $patron = $builder->build_object(
{
class => 'Koha::Patrons',
value => { flags => 0 }
}
);
$patron->set_password( { password => $password, skip_validation => 1 } );
my $unauth_userid = $patron->userid;
my $smtp_server_id =
$builder->build_object( { class => 'Koha::SMTP::Servers' } )->id;
# Unauthorized attempt to delete
$t->delete_ok(
"//$unauth_userid:$password@/api/v1/config/smtp_servers/$smtp_server_id"
)->status_is(403);
$t->delete_ok(
"//$userid:$password@/api/v1/config/smtp_servers/$smtp_server_id")
->status_is( 204, 'SWAGGER3.2.4' )->content_is( '', 'SWAGGER3.3.4' );
$t->delete_ok(
"//$userid:$password@/api/v1/config/smtp_servers/$smtp_server_id")
->status_is(404);
$schema->storage->txn_rollback;
};
Loading…
Cancel
Save