Bug 24228 - Add a parameter to recursively embed objects in Koha::Object(s)->to_api
Summary: Add a parameter to recursively embed objects in Koha::Object(s)->to_api
Status: CLOSED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: REST API (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement
Assignee: Agustín Moyano
QA Contact: Martin Renvoize (ashimema)
URL:
Keywords:
Depends on: 23843 23893
Blocks: 24302 24366
  Show dependency tree / graph
 
Reported: 2019-12-12 13:02 UTC by Tomás Cohen Arazi (tcohen)
Modified: 2021-06-14 21:28 UTC (History)
9 users (show)

See Also:
Change sponsored?: ---
Patch complexity: Small patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
This patch introduces a parameter to the Koha::Object class ('embed') that should be a hashref pointing to a data structure following what's documented in the code. This parameter allows the caller to specify things to embed recursively in the API representation of the object. For example: you could request a biblio object with its items attached, like this: $biblio_json = $biblio->to_api({ embed => { items => {} } }); The names specified for embedding, are used as attribute names on the resulting JSON object, and are expected to be class accessors. The main use of this is the API, as introduced by bug 24302. Koha::Objects->to_api is adjusted to pass its parameters down to the Koha::Object.
Version(s) released in:
20.05.00, 19.11.02
Circulation function:

Attachments
Bug 24228: Add parameters to Koha::Object->to_api to automatically embed objects (8.32 KB, patch)
2019-12-20 23:03 UTC, Agustín Moyano 		Details | Diff | Splinter Review
Bug 24228: Add parameters to Koha::Object(s)->to_api to automatically embed objects (5.20 KB, patch)
2019-12-23 15:40 UTC, Tomás Cohen Arazi (tcohen) 		Details | Diff | Splinter Review
Bug 24228: Make ->to_api params a hashref (8.98 KB, patch)
2019-12-23 15:40 UTC, Tomás Cohen Arazi (tcohen) 		Details | Diff | Splinter Review
Bug 24228: Make ->to_api params a hashref (9.66 KB, patch)
2019-12-23 17:49 UTC, Tomás Cohen Arazi (tcohen) 		Details | Diff | Splinter Review
Bug 24228: Make ->to_api params a hashref (9.49 KB, patch)
2019-12-24 14:15 UTC, Tomás Cohen Arazi (tcohen) 		Details | Diff | Splinter Review
Bug 24228: Add parameters to Koha::Object(s)->to_api to automatically embed objects (5.25 KB, patch)
2019-12-26 21:22 UTC, Agustín Moyano 		Details | Diff | Splinter Review
Bug 24228: Make ->to_api params a hashref (9.54 KB, patch)
2019-12-26 21:22 UTC, Agustín Moyano 		Details | Diff | Splinter Review
Bug 24228: (follow-up) Check wether each child or children can('to_api') and throw exception otherwise (2.55 KB, patch)
2019-12-26 22:31 UTC, Agustín Moyano 		Details | Diff | Splinter Review
Bug 24228: Make ->to_api params a hashref (11.99 KB, patch)
2019-12-30 18:08 UTC, Tomás Cohen Arazi (tcohen) 		Details | Diff | Splinter Review
Bug 24228: Add parameters to Koha::Object(s)->to_api to automatically embed objects (5.89 KB, patch)
2019-12-30 19:11 UTC, Tomás Cohen Arazi (tcohen) 		Details | Diff | Splinter Review
Bug 24228: Make ->to_api params a hashref (11.93 KB, patch)
2019-12-30 19:11 UTC, Tomás Cohen Arazi (tcohen) 		Details | Diff | Splinter Review
Bug 24228: Add parameters to Koha::Object(s)->to_api to automatically embed objects (5.96 KB, patch)
2020-01-07 19:12 UTC, Kyle M Hall (khall) 		Details | Diff | Splinter Review
Bug 24228: Make ->to_api params a hashref (12.00 KB, patch)
2020-01-07 19:12 UTC, Kyle M Hall (khall) 		Details | Diff | Splinter Review
Show Obsolete (11) View All Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Tomás Cohen Arazi (tcohen) 2019-12-12 13:02:17 UTC 
Using a syntax similar to MongoDB's dot notation, we need a way to specify which relations should be followed for recursively embedding objects. For example:

$patron->to_api({ embed => { checkouts => { 'pickup_location' => 1 }, credits => 1 } })
Comment 1 Agustín Moyano 2019-12-20 23:03:26 UTC 
Created attachment 96543 [details] [review]
Bug 24228: Add parameters to Koha::Object->to_api to automatically embed objects

This patch adds the posibility to define 'x-koha-embed' parameter in swagger and in request headers.

If 'x-koha-embed' header is present, in Koha::REST::V1::Auth it's compared with the whitelist defined in swagger through the 'x-koha-embed' parameter, placed at the same level of x-koha-authorization.

Whitelist should be composed of DBIC relations (optinally chained by '.') that has the corresponding method in Koha::Object.

To test:
1. Apply this patch
2. prove t/db_dependent/Koha/Object.t
Comment 2 Tomás Cohen Arazi (tcohen) 2019-12-23 15:40:11 UTC 
Created attachment 96612 [details] [review]
Bug 24228: Add parameters to Koha::Object(s)->to_api to automatically embed objects

This patch makes Koha::Object(s)->to_api have an 'embeds' parameter that
using dot notation (e.g. resource.related_resource.another_one) allows
embedding objects recursively.

To test:
1. Apply this patch
2. prove t/db_dependent/Koha/Object.t

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 3 Tomás Cohen Arazi (tcohen) 2019-12-23 15:40:14 UTC Comment hidden (obsolete)
Comment 4 Tomás Cohen Arazi (tcohen) 2019-12-23 17:49:59 UTC Comment hidden (obsolete)
Comment 5 Tomás Cohen Arazi (tcohen) 2019-12-24 14:15:41 UTC Comment hidden (obsolete)
Comment 6 Tomás Cohen Arazi (tcohen) 2019-12-24 14:16:33 UTC 
Changed the embed structure to ease x-koha-embed -> to_api param translation.
Comment 7 Agustín Moyano 2019-12-26 21:22:55 UTC 
Created attachment 96644 [details] [review]
Bug 24228: Add parameters to Koha::Object(s)->to_api to automatically embed objects

This patch makes Koha::Object(s)->to_api have an 'embeds' parameter that
using dot notation (e.g. resource.related_resource.another_one) allows
embedding objects recursively.

To test:
1. Apply this patch
2. prove t/db_dependent/Koha/Object.t

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Agustin Moyano <agustinmoyano@theke.io>
Comment 8 Agustín Moyano 2019-12-26 21:22:59 UTC Comment hidden (obsolete)
Comment 9 Agustín Moyano 2019-12-26 22:31:36 UTC Comment hidden (obsolete)
Comment 10 Tomás Cohen Arazi (tcohen) 2019-12-27 13:34:31 UTC 
(In reply to Agustín Moyano from comment #9)
> Created attachment 96646 [details] [review] [review]
> Bug 24228: (follow-up) Check wether each child or children can('to_api') and
> throw exception otherwise

Agustín, I'm not sure about your follow-up. I think it might be possible that we want to embed things that are not strictly Koha::Object-derived. I would prefer to leave it to the controller or the OpenAPI plugin to validate the result.

Also, there should be tests for the changed behavior.
Comment 11 Tomás Cohen Arazi (tcohen) 2019-12-30 18:08:33 UTC Comment hidden (obsolete)
Comment 12 Tomás Cohen Arazi (tcohen) 2019-12-30 19:10:32 UTC 
Rebasing on top of 23893.
Comment 13 Tomás Cohen Arazi (tcohen) 2019-12-30 19:11:05 UTC 
Created attachment 96686 [details] [review]
Bug 24228: Add parameters to Koha::Object(s)->to_api to automatically embed objects

This patch makes Koha::Object(s)->to_api have an 'embeds' parameter that
using dot notation (e.g. resource.related_resource.another_one) allows
embedding objects recursively.

To test:
1. Apply this patch
2. prove t/db_dependent/Koha/Object.t

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Agustin Moyano <agustinmoyano@theke.io>
Comment 14 Tomás Cohen Arazi (tcohen) 2019-12-30 19:11:10 UTC 
Created attachment 96687 [details] [review]
Bug 24228: Make ->to_api params a hashref

This patch makes the parameters for Koha::Object(s)->to_api a hashref
preparing the ground for new parameters. The proposed syntax is:

$object->to_api(
    {
        embed => {
            'items' => {
                'children' => {
                    'homebranch' => {}
                }
            }
        }
    }
);

Tests are added for the Koha::Objects implementation and tests for
Koha::Object are adjusted to the new syntax, and a test for the single
result accessor is added as well.

To test:
1. Apply this patches
2. Run:
   $ kshell
  k$ prove t/db_dependent/Koha/Object.t t/db_dependent/Koha/Objects.t
=> SUCCESS: Tests pass!
3. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 15 Kyle M Hall (khall) 2020-01-07 19:12:09 UTC 
Created attachment 96954 [details] [review]
Bug 24228: Add parameters to Koha::Object(s)->to_api to automatically embed objects

This patch makes Koha::Object(s)->to_api have an 'embeds' parameter that
using dot notation (e.g. resource.related_resource.another_one) allows
embedding objects recursively.

To test:
1. Apply this patch
2. prove t/db_dependent/Koha/Object.t

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Agustin Moyano <agustinmoyano@theke.io>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 16 Kyle M Hall (khall) 2020-01-07 19:12:22 UTC 
Created attachment 96955 [details] [review]
Bug 24228: Make ->to_api params a hashref

This patch makes the parameters for Koha::Object(s)->to_api a hashref
preparing the ground for new parameters. The proposed syntax is:

$object->to_api(
    {
        embed => {
            'items' => {
                'children' => {
                    'homebranch' => {}
                }
            }
        }
    }
);

Tests are added for the Koha::Objects implementation and tests for
Koha::Object are adjusted to the new syntax, and a test for the single
result accessor is added as well.

To test:
1. Apply this patches
2. Run:
   $ kshell
  k$ prove t/db_dependent/Koha/Object.t t/db_dependent/Koha/Objects.t
=> SUCCESS: Tests pass!
3. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 17 Martin Renvoize (ashimema) 2020-01-08 15:06:45 UTC 
The uses here are clear and the code is mostly simple to follow.. Passing QA and pushing, no doubt there will be refinements down the line but there's nothing that stands out as introducing regressions or bad practice.
Comment 18 Martin Renvoize (ashimema) 2020-01-08 15:07:59 UTC 
Nice work everyone!

Pushed to master for 20.05
Comment 19 Joy Nelson 2020-01-18 16:26:13 UTC 
Pushed to 19.11.x branch for 19.11.02
Comment 20 Jonathan Druart 2020-01-22 15:05:00 UTC 
What does $curr mean?
Comment 21 Jonathan Druart 2020-01-22 15:05:42 UTC 
(In reply to Jonathan Druart from comment #20)
> What does $curr mean?

ok, it's current I guess.