Attachment 91401 Details for Bug 16825 – Bug 16825: Add API route for getting an item

[patch] Bug 16825: Add API route for getting an item

Bug-16825-Add-API-route-for-getting-an-item.patch (text/plain), 20.12 KB, created by Michal Denar on 2019-07-08 07:35:24 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Michal Denar

Created: 2019-07-08 07:35:24 UTC

Size: 20.12 KB

patch

obsolete

>From b6e2b693bb2e39c2b5231356f53c7766a6e1afae Mon Sep 17 00:00:00 2001
>From: Lari Taskula <larit@student.uef.fi>
>Date: Mon, 27 Jun 2016 16:03:49 +0300
>Subject: [PATCH] Bug 16825: Add API route for getting an item
>
>GET /api/v1/items/{item_id} Gets one Item
>
>This patch adds route to get one item from koha.items table.
>
>To test:
>1. Apply patch
>2. Open a browser tab on Koha staff and log in (to create CGISESSID
>   cookie).
>3. Send GET request to http://yourlibrary/api/v1/items/YYY
>   where YYY is an existing itemnumber.
>4. Make sure the returned data is correct.
>5. Run unit tests in t/db_dependent/api/v1/items.t
>
>Sponsored-by: Koha-Suomi Oy
>
>Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
>Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
>Signed-off-by: Michal Denar <black23@gmail.com>
>---
> Koha/REST/V1/Items.pm                | 216 +++++++++++++++++++++++++++++++++++
> api/v1/swagger/definitions.json      |   3 +
> api/v1/swagger/definitions/item.json | 183 +++++++++++++++++++++++++++++
> api/v1/swagger/parameters.json       |   3 +
> api/v1/swagger/parameters/item.json  |   9 ++
> api/v1/swagger/paths.json            |   3 +
> api/v1/swagger/paths/items.json      |  52 +++++++++
> t/db_dependent/api/v1/items.t        |  81 +++++++++++++
> 8 files changed, 550 insertions(+)
> create mode 100644 Koha/REST/V1/Items.pm
> create mode 100644 api/v1/swagger/definitions/item.json
> create mode 100644 api/v1/swagger/parameters/item.json
> create mode 100644 api/v1/swagger/paths/items.json
> create mode 100644 t/db_dependent/api/v1/items.t
>
>diff --git a/Koha/REST/V1/Items.pm b/Koha/REST/V1/Items.pm
>new file mode 100644
>index 0000000000..d93af2e6bc
>--- /dev/null
>+++ b/Koha/REST/V1/Items.pm
>@@ -0,0 +1,216 @@
>+package Koha::REST::V1::Items;
>+
>+# 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, write to the Free Software Foundation, Inc.,
>+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
>+
>+use Modern::Perl;
>+
>+use Mojo::Base 'Mojolicious::Controller';
>+use Mojo::JSON;
>+
>+use C4::Auth qw( haspermission );
>+use C4::Items qw( GetHiddenItemnumbers );
>+
>+use Koha::Items;
>+
>+use Try::Tiny;
>+
>+sub get {
>+    my $c = shift->openapi->valid_input or return;
>+
>+    my $item;
>+    try {
>+        $item = Koha::Items->find($c->validation->param('item_id'));
>+        return $c->render( status => 200, openapi => _to_api( $item->TO_JSON ) );
>+    }
>+    catch {
>+        unless ( defined $item ) {
>+            return $c->render( status => 404,
>+                               openapi => { error => 'Item not found'} );
>+        }
>+        if ( $_->isa('DBIx::Class::Exception') ) {
>+            return $c->render( status  => 500,
>+                               openapi => { error => $_->{msg} } );
>+        }
>+        else {
>+            return $c->render( status => 500,
>+                openapi => { error => "Something went wrong, check the logs."} );
>+        }
>+    };
>+}
>+
>+=head3 _to_api
>+
>+Helper function that maps unblessed Koha::Hold objects into REST api
>+attribute names.
>+
>+=cut
>+
>+sub _to_api {
>+    my $item = shift;
>+
>+    # Rename attributes
>+    foreach my $column ( keys %{ $Koha::REST::V1::Items::to_api_mapping } ) {
>+        my $mapped_column = $Koha::REST::V1::Items::to_api_mapping->{$column};
>+        if (    exists $item->{ $column }
>+             && defined $mapped_column )
>+        {
>+            # key != undef
>+            $item->{ $mapped_column } = delete $item->{ $column };
>+        }
>+        elsif (    exists $item->{ $column }
>+                && !defined $mapped_column )
>+        {
>+            # key == undef
>+            delete $item->{ $column };
>+        }
>+    }
>+
>+    return $item;
>+}
>+
>+=head3 _to_model
>+
>+Helper function that maps REST api objects into Koha::Hold
>+attribute names.
>+
>+=cut
>+
>+sub _to_model {
>+    my $item = shift;
>+
>+    foreach my $attribute ( keys %{ $Koha::REST::V1::Items::to_model_mapping } ) {
>+        my $mapped_attribute = $Koha::REST::V1::Items::to_model_mapping->{$attribute};
>+        if (    exists $item->{ $attribute }
>+             && defined $mapped_attribute )
>+        {
>+            # key => !undef
>+            $item->{ $mapped_attribute } = delete $item->{ $attribute };
>+        }
>+        elsif (    exists $item->{ $attribute }
>+                && !defined $mapped_attribute )
>+        {
>+            # key => undef / to be deleted
>+            delete $item->{ $attribute };
>+        }
>+    }
>+
>+    return $item;
>+}
>+
>+=head2 Global variables
>+
>+=head3 $to_api_mapping
>+
>+=cut
>+
>+our $to_api_mapping = {
>+    itemnumber => 'item_id',
>+    biblionumber => 'biblio_id',
>+    biblioitemnumber => undef,
>+    barcode => 'external_id',
>+    dateaccessioned => 'acquisition_date',
>+    booksellerid => 'acquisition_source',
>+    homebranch => 'home_library_id',
>+    price => 'purchase_price',
>+    replacementprice => 'replacement_price',
>+    replacementpricedate => 'replacement_price_date',
>+    datelastborrowed => 'last_checkout_date',
>+    datelastseen => 'last_seen_date',
>+    stack => undef,
>+    notforloan => 'not_for_loan_status',
>+    damaged => 'damaged_status',
>+    damaged_on => 'damaged_date',
>+    itemlost => 'lost_status',
>+    itemlost_on => 'lost_date',
>+    withdrawn => 'withdrawn',
>+    withdrawn_on => 'withdrawn_date',
>+    itemcallnumber => 'callnumber',
>+    coded_location_qualifier => 'coded_location_qualifier',
>+    issues => 'checkouts_count',
>+    renewals => 'renewals_count',
>+    reserves => 'holds_count',
>+    restricted => 'restricted_status',
>+    itemnotes => 'public_notes',
>+    itemnotes_nonpublic => 'internal_notes',
>+    holdingbranch => 'holding_library_id',
>+    paidfor => undef,
>+    timestamp => 'timestamp',
>+    location => 'location',
>+    permanent_location => 'permanent_location',
>+    onloan => 'checked_out_date',
>+    cn_source => 'call_number_source',
>+    cn_sort => 'call_number_sort',
>+    ccode => 'collection_code',
>+    materials => 'materials_notes',
>+    uri => 'uri',
>+    itype => 'item_type',
>+    more_subfields_xml => 'extended_subfields',
>+    enumchron => 'serial_issue_number',
>+    copynumber => 'copy_number',
>+    stocknumber => 'inventory_number',
>+    new_status => 'new_status'
>+};
>+
>+=head3 $to_model_mapping
>+
>+=cut
>+
>+our $to_model_mapping = {
>+    item_id => 'itemnumber',
>+    biblio_id => 'biblionumber',
>+    external_id => 'barcode',
>+    acquisition_date => 'dateaccessioned',
>+    acquisition_source => 'booksellerid',
>+    home_library_id => 'homebranch',
>+    purchase_price => 'price',
>+    replacement_price => 'replacementprice',
>+    replacement_price_date => 'replacementpricedate',
>+    last_checkout_date => 'datelastborrowed',
>+    last_seen_date => 'datelastseen',
>+    not_for_loan_status => 'notforloan',
>+    damaged_status => 'damaged',
>+    damaged_date => 'damaged_on',
>+    lost_status => 'itemlost',
>+    lost_date => 'itemlost_on',
>+    withdrawn => 'withdrawn',
>+    withdrawn_date => 'withdrawn_on',
>+    callnumber => 'itemcallnumber',
>+    coded_location_qualifier => 'coded_location_qualifier',
>+    checkouts_count => 'issues',
>+    renewals_count => 'renewals',
>+    holds_count => 'reserves',
>+    restricted_status => 'restricted',
>+    public_notes => 'itemnotes',
>+    internal_notes => 'itemnotes_nonpublic',
>+    holding_library_id => 'holdingbranch',
>+    timestamp => 'timestamp',
>+    location => 'location',
>+    permanent_location => 'permanent_location',
>+    checked_out_date => 'onloan',
>+    call_number_source => 'cn_source',
>+    call_number_sort => 'cn_sort',
>+    collection_code => 'ccode',
>+    materials_notes => 'materials',
>+    uri => 'uri',
>+    item_type => 'itype',
>+    extended_subfields => 'more_subfields_xml',
>+    serial_issue_number => 'enumchron',
>+    copy_number => 'copynumber',
>+    inventory_number => 'stocknumber',
>+    new_status => 'new_status'
>+};
>+
>+1;
>diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json
>index e3001b5e60..4ac42cf925 100644
>--- a/api/v1/swagger/definitions.json
>+++ b/api/v1/swagger/definitions.json
>@@ -23,6 +23,9 @@
>   "library": {
>     "$ref": "definitions/library.json"
>   },
>+  "item": {
>+    "$ref": "definitions/item.json"
>+  },
>   "patron": {
>     "$ref": "definitions/patron.json"
>   },
>diff --git a/api/v1/swagger/definitions/item.json b/api/v1/swagger/definitions/item.json
>new file mode 100644
>index 0000000000..2643bc113f
>--- /dev/null
>+++ b/api/v1/swagger/definitions/item.json
>@@ -0,0 +1,183 @@
>+{
>+  "type": "object",
>+  "properties": {
>+    "item_id": {
>+      "type": "integer",
>+      "description": "Internal item identifier"
>+    },
>+    "biblio_id": {
>+      "type": "integer",
>+      "description": "Internal identifier for the parent bibliographic record"
>+    },
>+    "external_id": {
>+      "type": ["string", "null"],
>+      "description": "The item's barcode"
>+    },
>+    "acquisition_date": {
>+      "type": ["string", "null"],
>+      "format": "date",
>+      "description": "The date the item was acquired"
>+    },
>+    "acquisition_source": {
>+      "type": ["string", "null"],
>+      "description": "Information about the acquisition source (it is not really a vendor id)"
>+    },
>+    "home_library_id": {
>+      "type": ["string", "null"],
>+      "description": "Internal library id for the library the item belongs to"
>+    },
>+    "purchase_price": {
>+      "type": ["number", "null"],
>+      "description": "Purchase price"
>+    },
>+    "replacement_price": {
>+      "type": ["number", "null"],
>+      "description": "Cost the library charges to replace the item (e.g. if lost)"
>+    },
>+    "replacement_price_date": {
>+      "type": ["string", "null"],
>+      "format": "date",
>+      "description": "The date the replacement price is effective from"
>+    },
>+    "last_checkout_date": {
>+      "type": ["string", "null"],
>+      "format": "date",
>+      "description": "The date the item was last checked out"
>+    },
>+    "last_seen_date": {
>+      "type": ["string", "null"],
>+      "format": "date",
>+      "description": "The date the item barcode was last scanned"
>+    },
>+    "not_for_loan_status": {
>+      "type": "integer",
>+      "description": "Authorized value defining why this item is not for loan"
>+    },
>+    "damaged_status": {
>+      "type": "integer",
>+      "description": "Authorized value defining this item as damaged"
>+    },
>+    "damaged_date": {
>+      "type": ["string", "null"],
>+      "description": "The date and time an item was last marked as damaged, NULL if not damaged"
>+    },
>+    "lost_status": {
>+      "type": "integer",
>+      "description": "Authorized value defining this item as lost"
>+    },
>+    "lost_date": {
>+      "type": ["string", "null"],
>+      "format": "date-time",
>+      "description": "The date and time an item was last marked as lost, NULL if not lost"
>+    },
>+    "withdrawn": {
>+      "type": "integer",
>+      "description": "Authorized value defining this item as withdrawn"
>+    },
>+    "withdrawn_date": {
>+      "type": ["string", "null"],
>+      "format": "date-time",
>+      "description": "The date and time an item was last marked as withdrawn, NULL if not withdrawn"
>+    },
>+    "callnumber": {
>+      "type": ["string", "null"],
>+      "description": "Call number for this item"
>+    },
>+    "coded_location_qualifier": {
>+      "type": ["string", "null"],
>+      "description": "Coded location qualifier"
>+    },
>+    "checkouts_count": {
>+      "type": ["integer", "null"],
>+      "description": "Number of times this item has been checked out/issued"
>+    },
>+    "renewals_count": {
>+      "type": ["integer", "null"],
>+      "description": "Number of times this item has been renewed"
>+    },
>+    "holds_count": {
>+      "type": ["integer", "null"],
>+      "description": "Number of times this item has been placed on hold/reserved"
>+    },
>+    "restricted_status": {
>+      "type": ["integer", "null"],
>+      "description": "Authorized value defining use restrictions for this item"
>+    },
>+    "public_notes": {
>+      "type": ["string", "null"],
>+      "description": "Public notes on this item"
>+    },
>+    "internal_notes": {
>+      "type": ["string", "null"],
>+      "description": "Non-public notes on this item"
>+    },
>+    "holding_library_id": {
>+      "type": ["string", "null"],
>+      "description": "Library that is currently in possession item"
>+    },
>+    "timestamp": {
>+      "type": "string",
>+      "format": "date-time",
>+      "description": "Date and time this item was last altered"
>+    },
>+    "location": {
>+      "type": ["string", "null"],
>+      "description": "Authorized value for the shelving location for this item"
>+    },
>+    "permanent_location": {
>+      "type": ["string", "null"],
>+      "description": "Linked to the CART and PROC temporary locations feature, stores the permanent shelving location"
>+    },
>+    "checked_out_date": {
>+      "type": ["string", "null"],
>+      "format": "date",
>+      "description": "Defines if item is checked out (NULL for not checked out, and checkout date for checked out)"
>+    },
>+    "call_number_source": {
>+      "type": ["string", "null"],
>+      "description": "Classification source used on this item"
>+    },
>+    "call_number_sort": {
>+      "type": ["string", "null"],
>+      "description": "?"
>+    },
>+    "collection_code": {
>+      "type": ["string", "null"],
>+      "description": "Authorized value for the collection code associated with this item"
>+    },
>+    "materials_notes": {
>+      "type": ["string", "null"],
>+      "description": "Materials specified"
>+    },
>+    "uri": {
>+      "type": ["string", "null"],
>+      "description": "URL for the item"
>+    },
>+    "item_type": {
>+      "type": ["string", "null"],
>+      "description": "Itemtype defining the type for this item"
>+    },
>+    "extended_subfields": {
>+      "type": ["string", "null"],
>+      "description": "Additional 952 subfields in XML format"
>+    },
>+    "serial_issue_number": {
>+      "type": ["string", "null"],
>+      "description": "serial enumeration/chronology for the item"
>+    },
>+    "copy_number": {
>+      "type": ["string", "null"],
>+      "description": "Copy number"
>+    },
>+    "inventory_number": {
>+      "type": ["string", "null"],
>+      "description": "Inventory number"
>+    },
>+    "new_status": {
>+      "type": ["string", "null"],
>+      "description": "'new' value, whatever free-text information."
>+    }
>+  },
>+  "additionalProperties": false,
>+  "required": ["item_id", "biblio_id", "not_for_loan_status", "damaged_status", "lost_status", "withdrawn"]
>+}
>diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json
>index fce13be958..b5aa33ecbb 100644
>--- a/api/v1/swagger/parameters.json
>+++ b/api/v1/swagger/parameters.json
>@@ -17,6 +17,9 @@
>   "library_id_pp": {
>     "$ref": "parameters/library.json#/library_id_pp"
>   },
>+  "item_id_pp": {
>+    "$ref": "parameters/item.json#/item_id_pp"
>+  },
>   "vendoridPathParam": {
>     "$ref": "parameters/vendor.json#/vendoridPathParam"
>   },
>diff --git a/api/v1/swagger/parameters/item.json b/api/v1/swagger/parameters/item.json
>new file mode 100644
>index 0000000000..8e54e9de37
>--- /dev/null
>+++ b/api/v1/swagger/parameters/item.json
>@@ -0,0 +1,9 @@
>+{
>+  "item_id_pp": {
>+    "name": "item_id",
>+    "in": "path",
>+    "description": "Internal item identifier",
>+    "required": true,
>+    "type": "integer"
>+  }
>+}
>diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json
>index 5d544f5c5e..946de0a6a4 100644
>--- a/api/v1/swagger/paths.json
>+++ b/api/v1/swagger/paths.json
>@@ -47,6 +47,9 @@
>   "/checkouts/{checkout_id}/allows_renewal": {
>     "$ref": "paths/checkouts.json#/~1checkouts~1{checkout_id}~1allows_renewal"
>   },
>+  "/items/{item_id}": {
>+    "$ref": "paths/items.json#/~1items~1{item_id}"
>+  },
>   "/patrons": {
>     "$ref": "paths/patrons.json#/~1patrons"
>   },
>diff --git a/api/v1/swagger/paths/items.json b/api/v1/swagger/paths/items.json
>new file mode 100644
>index 0000000000..28e136d7a9
>--- /dev/null
>+++ b/api/v1/swagger/paths/items.json
>@@ -0,0 +1,52 @@
>+{
>+  "/items/{item_id}": {
>+    "get": {
>+      "x-mojo-to": "Items#get",
>+      "operationId": "getItem",
>+      "tags": ["items"],
>+      "parameters": [{
>+          "$ref": "../parameters.json#/item_id_pp"
>+        }
>+      ],
>+      "consumes": ["application/json"],
>+      "produces": ["application/json"],
>+      "responses": {
>+        "200": {
>+          "description": "An item",
>+          "schema": {
>+            "$ref": "../definitions.json#/item"
>+          }
>+        },
>+        "400": {
>+          "description": "Missing or wrong parameters",
>+          "schema": {
>+            "$ref": "../definitions.json#/error"
>+          }
>+        },
>+        "404": {
>+          "description": "Item not found",
>+          "schema": {
>+            "$ref": "../definitions.json#/error"
>+          }
>+        },
>+        "500": {
>+          "description": "Internal server error",
>+          "schema": {
>+            "$ref": "../definitions.json#/error"
>+          }
>+        },
>+        "503": {
>+          "description": "Under maintenance",
>+          "schema": {
>+            "$ref": "../definitions.json#/error"
>+          }
>+        }
>+      },
>+      "x-koha-authorization": {
>+        "permissions": {
>+          "catalogue": "1"
>+        }
>+      }
>+    }
>+  }
>+}
>diff --git a/t/db_dependent/api/v1/items.t b/t/db_dependent/api/v1/items.t
>new file mode 100644
>index 0000000000..a3724dcdc4
>--- /dev/null
>+++ b/t/db_dependent/api/v1/items.t
>@@ -0,0 +1,81 @@
>+#!/usr/bin/env perl
>+
>+# Copyright 2016 Koha-Suomi
>+#
>+# 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, write to the Free Software Foundation, Inc.,
>+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
>+
>+use Modern::Perl;
>+
>+use Test::More tests => 1;
>+use Test::Mojo;
>+use Test::Warn;
>+
>+use t::lib::TestBuilder;
>+use t::lib::Mocks;
>+
>+use C4::Auth;
>+use Koha::Items;
>+use Koha::Database;
>+
>+my $schema  = Koha::Database->new->schema;
>+my $builder = t::lib::TestBuilder->new;
>+
>+t::lib::Mocks::mock_preference( 'RESTBasicAuth', 1 );
>+
>+my $t = Test::Mojo->new('Koha::REST::V1');
>+
>+subtest 'get() tests' => sub {
>+
>+    plan tests => 9;
>+
>+    $schema->storage->txn_begin;
>+
>+    my $item = $builder->build_object( { class => 'Koha::Items' } );
>+    my $patron = $builder->build_object({
>+        class => 'Koha::Patrons',
>+        value => { flags => 4 }
>+    });
>+
>+    my $nonprivilegedpatron = $builder->build_object({
>+        class => 'Koha::Patrons',
>+        value => { flags => 0 }
>+    });
>+
>+    my $password = 'thePassword123';
>+
>+    $nonprivilegedpatron->set_password({ password => $password, skip_validation => 1 });
>+    my $userid = $nonprivilegedpatron->userid;
>+
>+    $t->get_ok( "//$userid:$password@/api/v1/items/" . $item->itemnumber )
>+      ->status_is(403)
>+      ->json_is( '/error' => 'Authorization failure. Missing required permission(s).' );
>+
>+    $patron->set_password({ password => $password, skip_validation => 1 });
>+    $userid = $patron->userid;
>+
>+    $t->get_ok( "//$userid:$password@/api/v1/items/" . $item->itemnumber )
>+      ->status_is( 200, 'SWAGGER3.2.2' )
>+      ->json_is( '' => Koha::REST::V1::Items::_to_api( $item->TO_JSON ), 'SWAGGER3.3.2' );
>+
>+    my $non_existent_code = $item->itemnumber;
>+    $item->delete;
>+
>+    $t->get_ok( "//$userid:$password@/api/v1/items/" . $non_existent_code )
>+      ->status_is(404)
>+      ->json_is( '/error' => 'Item not found' );
>+
>+    $schema->storage->txn_rollback;
>+};
>-- 
>2.11.0

Actions: View | Diff | Splinter Review

Attachments on bug 16825: 52943 | 52947 | 53035 | 53108 | 53111 | 53222 | 53837 | 53921 | 53923 | 54052 | 54686 | 54687 | 56122 | 56123 | 56124 | 56125 | 56131 | 56133 | 56290 | 56292 | 56293 | 61176 | 64275 | 65007 | 67865 | 91051 | 91061 | 91124 | 91399 | 91401 | 92639