From 4a6b6ab2fcd6c35129e6162d3e3893260e3d03f4 Mon Sep 17 00:00:00 2001 From: Martin Renvoize Date: Tue, 25 Oct 2022 13:14:19 +0100 Subject: [PATCH] Bug 31028: Add API's for tickets This patch adds basic CRUD API's for the ticket endpoints. --- Koha/REST/V1/Tickets.pm | 150 +++++++++++++++ Koha/Ticket.pm | 13 ++ api/v1/swagger/definitions/ticket.yaml | 51 +++++ api/v1/swagger/paths/tickets.yaml | 252 +++++++++++++++++++++++++ api/v1/swagger/swagger.yaml | 14 ++ 5 files changed, 480 insertions(+) create mode 100644 Koha/REST/V1/Tickets.pm create mode 100644 api/v1/swagger/definitions/ticket.yaml create mode 100644 api/v1/swagger/paths/tickets.yaml diff --git a/Koha/REST/V1/Tickets.pm b/Koha/REST/V1/Tickets.pm new file mode 100644 index 0000000000..2e5a418b63 --- /dev/null +++ b/Koha/REST/V1/Tickets.pm @@ -0,0 +1,150 @@ +package Koha::REST::V1::Tickets; + +# 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::Ticket; +use Koha::Tickets; +use Koha::Ticket::Update; +use Koha::Ticket::Updates; + +use Try::Tiny qw( catch try ); + +=head1 API + +=head2 Methods + +=head3 list + +=cut + +sub list { + my $c = shift->openapi->valid_input or return; + + return try { + my $tickets_set = Koha::Tickets->new; + my $tickets = $c->objects->search($tickets_set); + return $c->render( status => 200, openapi => $tickets ); + } + catch { + $c->unhandled_exception($_); + }; + +} + +=head3 get + +=cut + +sub get { + my $c = shift->openapi->valid_input or return; + + return try { + my $ticket = Koha::Tickets->find( $c->validation->param('ticket_id') ); + unless ($ticket) { + return $c->render( + status => 404, + openapi => { error => "Ticket not found" } + ); + } + + return $c->render( status => 200, openapi => $ticket->to_api ); + } + catch { + $c->unhandled_exception($_); + } +} + +=head3 add + +=cut + +sub add { + my $c = shift->openapi->valid_input or return; + + return try { + my $body = $c->validation->param('body'); + my $ticket = Koha::Ticket->new_from_api($body)->store; + $ticket->discard_changes; + $c->res->headers->location( + $c->req->url->to_string . '/' . $ticket->id ); + return $c->render( + status => 201, + openapi => $ticket->to_api + ); + } + catch { + $c->unhandled_exception($_); + }; +} + +=head3 update + +=cut + +sub update { + my $c = shift->openapi->valid_input or return; + + my $ticket = Koha::Tickets->find( $c->validation->param('ticket_id') ); + + if ( not defined $ticket ) { + return $c->render( + status => 404, + openapi => { error => "Object not found" } + ); + } + + return try { + $ticket->set_from_api( $c->validation->param('body') ); + $ticket->store(); + return $c->render( status => 200, openapi => $ticket->to_api ); + } + catch { + $c->unhandled_exception($_); + }; +} + +=head3 delete + +=cut + +sub delete { + my $c = shift->openapi->valid_input or return; + + my $ticket = Koha::Tickets->find( $c->validation->param('ticket_id') ); + if ( not defined $ticket ) { + return $c->render( + status => 404, + openapi => { error => "Object not found" } + ); + } + + return try { + $ticket->delete; + return $c->render( + status => 204, + openapi => q{} + ); + } + catch { + $c->unhandled_exception($_); + }; +} + +1; diff --git a/Koha/Ticket.pm b/Koha/Ticket.pm index 2435d31e38..e557203e23 100644 --- a/Koha/Ticket.pm +++ b/Koha/Ticket.pm @@ -100,6 +100,19 @@ sub add_update { =head2 Internal methods +=cut + +=head3 to_api_mapping + +This method returns the mapping for representing a Koha::Ticket object +on the API. + +=cut + +sub to_api_mapping { + return { id => 'ticket_id', }; +} + =head3 _type =cut diff --git a/api/v1/swagger/definitions/ticket.yaml b/api/v1/swagger/definitions/ticket.yaml new file mode 100644 index 0000000000..d3439e0443 --- /dev/null +++ b/api/v1/swagger/definitions/ticket.yaml @@ -0,0 +1,51 @@ +--- +type: object +properties: + ticket_id: + type: integer + description: Internal ticket identifier + reported_date: + type: + - string + - "null" + format: date-time + description: Date the ticket was reported + biblio: + type: + - object + - "null" + description: The object representing the biblio the ticket is related to + biblio_id: + type: integer + description: Internal identifier for the biblio the ticket is related to + title: + type: string + description: Ticket title + body: + type: string + description: Ticket details + reporter: + type: + - object + - "null" + description: The object representing the patron who reported the ticket + reporter_id: + type: integer + description: Internal identifier for the patron who reported the ticket + resolver: + type: + - object + - "null" + description: The object representing the user who resolved the ticket + resolver_id: + type: + - integer + - "null" + description: Internal identifier for the user who resolved the ticket + resolved_date: + type: + - string + - "null" + format: date-time + description: Date the ticket was resolved_date +additionalProperties: false diff --git a/api/v1/swagger/paths/tickets.yaml b/api/v1/swagger/paths/tickets.yaml new file mode 100644 index 0000000000..ad652a0d78 --- /dev/null +++ b/api/v1/swagger/paths/tickets.yaml @@ -0,0 +1,252 @@ +--- +/tickets: + get: + x-mojo-to: Tickets#list + operationId: listTickets + tags: + - tickets + summary: List tickets + produces: + - application/json + parameters: + - $ref: "../swagger.yaml#/parameters/match" + - $ref: "../swagger.yaml#/parameters/order_by" + - $ref: "../swagger.yaml#/parameters/page" + - $ref: "../swagger.yaml#/parameters/per_page" + - $ref: "../swagger.yaml#/parameters/q_param" + - $ref: "../swagger.yaml#/parameters/q_body" + - $ref: "../swagger.yaml#/parameters/q_header" + - $ref: "../swagger.yaml#/parameters/request_id_header" + - name: x-koha-embed + in: header + required: false + description: Embed list sent as a request header + type: array + items: + type: string + enum: + - reporter + - resolver + - biblio + collectionFormat: csv + responses: + "200": + description: A list of tickets + schema: + type: array + items: + $ref: "../swagger.yaml#/definitions/ticket" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: | + Internal server error. Possible `error_code` attribute values: + + * `internal_server_error` + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" + x-koha-authorization: + permissions: + catalogue: "1" + post: + x-mojo-to: Tickets#add + operationId: addTicket + tags: + - tickets + summary: Add ticket + parameters: + - name: body + in: body + description: A JSON object containing informations about the new hold + required: true + schema: + $ref: "../swagger.yaml#/definitions/ticket" + produces: + - application/json + responses: + "201": + description: Ticket added + schema: + $ref: "../swagger.yaml#/definitions/ticket" + "401": + description: Authentication required + schema: + $ref: "../swagger.yaml#/definitions/error" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: | + Internal server error. Possible `error_code` attribute values: + + * `internal_server_error` + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" + x-koha-authorization: + permissions: + catalogue: "1" +"/tickets/{ticket_id}": + get: + x-mojo-to: Tickets#get + operationId: getTicket + tags: + - tickets + summary: Get ticket + parameters: + - $ref: "../swagger.yaml#/parameters/ticket_id_pp" + produces: + - application/json + responses: + "200": + description: A ticket + schema: + $ref: "../swagger.yaml#/definitions/ticket" + "404": + description: Ticket not found + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: | + Internal server error. Possible `error_code` attribute values: + + * `internal_server_error` + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" + x-koha-authorization: + permissions: + catalogue: "1" + put: + x-mojo-to: Tickets#update + operationId: updateTicket + tags: + - tickets + summary: Update ticket + parameters: + - $ref: "../swagger.yaml#/parameters/ticket_id_pp" + - name: body + in: body + description: A ticket object + required: true + schema: + $ref: "../swagger.yaml#/definitions/ticket" + produces: + - application/json + responses: + "200": + description: A ticket + schema: + $ref: "../swagger.yaml#/definitions/ticket" + "401": + description: Authentication required + schema: + $ref: "../swagger.yaml#/definitions/error" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "404": + description: Ticket not found + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: Internal error + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" + x-koha-authorization: + permissions: + editcatalogue: edit_catalogue + delete: + x-mojo-to: Tickets#delete + operationId: deleteTicket + tags: + - tickets + summary: Delete ticket + parameters: + - $ref: "../swagger.yaml#/parameters/ticket_id_pp" + produces: + - application/json + responses: + "204": + description: Ticket deleted + "401": + description: Authentication required + schema: + $ref: "../swagger.yaml#/definitions/error" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "404": + description: Ticket not found + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: Internal error + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" + x-koha-authorization: + permissions: + editcatalogue: edit_catalogue +/public/tickets: + post: + x-mojo-to: Tickets#add + operationId: addTicketPublic + tags: + - tickets + summary: Add ticket + parameters: + - name: body + in: body + description: A JSON object containing informations about the new hold + required: true + schema: + $ref: "../swagger.yaml#/definitions/ticket" + produces: + - application/json + responses: + "201": + description: Ticket added + schema: + $ref: "../swagger.yaml#/definitions/ticket" + "401": + description: Authentication required + schema: + $ref: "../swagger.yaml#/definitions/error" + "403": + description: Access forbidden + schema: + $ref: "../swagger.yaml#/definitions/error" + "500": + description: | + Internal server error. Possible `error_code` attribute values: + + * `internal_server_error` + schema: + $ref: "../swagger.yaml#/definitions/error" + "503": + description: Under maintenance + schema: + $ref: "../swagger.yaml#/definitions/error" diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml index 696a73be8b..9c763bd21d 100644 --- a/api/v1/swagger/swagger.yaml +++ b/api/v1/swagger/swagger.yaml @@ -88,6 +88,8 @@ definitions: $ref: ./definitions/smtp_server.yaml suggestion: $ref: ./definitions/suggestion.yaml + ticket: + $ref: ./definitions/ticket.yaml transfer_limit: $ref: ./definitions/transfer_limit.yaml vendor: @@ -291,6 +293,8 @@ paths: $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_checkouts" "/public/patrons/{patron_id}/password": $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1password" + "/public/tickets": + $ref: "./paths/tickets.yaml#/~1public~1tickets" /quotes: $ref: ./paths/quotes.yaml#/~1quotes "/quotes/{quote_id}": @@ -311,6 +315,10 @@ paths: $ref: "./paths/suggestions.yaml#/~1suggestions~1{suggestion_id}" /suggestions/managers: $ref: paths/suggestions.yaml#/~1suggestions~1managers + "/tickets": + $ref: "./paths/tickets.yaml#/~1tickets" + "/tickets/{ticket_id}": + $ref: "./paths/tickets.yaml#/~1tickets~1{ticket_id}" /transfer_limits: $ref: ./paths/transfer_limits.yaml#/~1transfer_limits /transfer_limits/batch: @@ -563,6 +571,12 @@ parameters: name: suggestion_id required: true type: integer + ticket_id_pp: + description: Internal ticket identifier + in: path + name: ticket_id + required: true + type: integer transfer_limit_id_pp: description: Internal transfer limit identifier in: path -- 2.20.1