Bug 29810

Summary: Add embed options documentation
Product: Koha Reporter: Martin Renvoize (ashimema) <martin.renvoize>
Component: REST APIAssignee: Martin Renvoize (ashimema) <martin.renvoize>
Status: CLOSED FIXED QA Contact: Jonathan Druart <jonathan.druart>
Severity: enhancement    
Priority: P5 - low CC: fridolin.somers, jonathan.druart, kyle, lucas, mtj, tomascohen
Version: Main   
Hardware: All   
OS: All   
Change sponsored?: --- Patch complexity: Trivial patch
Documentation contact: Documentation submission:
Text to go in the release notes:
This patch adds documentation of the different embed options the REST API provides.
Version(s) released in:
22.05.00
Circulation function:
Bug Depends on: 30194    
Bug Blocks: 30536, 30542    
Attachments: Bug 29810: Add summary of x-koha-embed header to api spec
Bug 29810: Document x-koha-embed header on patrons endpoints
Bug 29810: Add summary of x-koha-embed header to api spec
Bug 29810: Document x-koha-embed header on patrons endpoints
Bug 29810: Document x-koha-embed header on checkouts endpoints
Bug 29810: Document x-koha-embed header on biblios endpoints
Bug 29810: Document x-koha-embed header on cash registers endpoints
Bug 29810: Document x-koha-embed header on libraries endpoints
Bug 29810: Document x-koha-embed header on orders endpoints
Bug 29810: Add summary of x-koha-embed header to api spec
Bug 29810: Document x-koha-embed header on patrons endpoints
Bug 29810: Document x-koha-embed header on checkouts endpoints
Bug 29810: Document x-koha-embed header on biblios endpoints
Bug 29810: Document x-koha-embed header on cash registers endpoints
Bug 29810: Document x-koha-embed header on libraries endpoints
Bug 29810: Document x-koha-embed header on orders endpoints
Bug 29810: Add summary of x-koha-embed header to api spec
Bug 29810: Document x-koha-embed header on patrons endpoints
Bug 29810: Document x-koha-embed header on checkouts endpoints
Bug 29810: Document x-koha-embed header on biblios endpoints
Bug 29810: Document x-koha-embed header on cash registers endpoints
Bug 29810: Document x-koha-embed header on libraries endpoints
Bug 29810: Document x-koha-embed header on orders endpoints
Debugging Tests
Bug 29810: Add summary of x-koha-embed header to api spec
Bug 29810: Document x-koha-embed header on patrons endpoints
Bug 29810: Document x-koha-embed header on checkouts endpoints
Bug 29810: Document x-koha-embed header on biblios endpoints
Bug 29810: Document x-koha-embed header on cash registers endpoints
Bug 29810: Document x-koha-embed header on libraries endpoints
Bug 29810: Document x-koha-embed header on orders endpoints
Bug 29810: Add 'x-koha-embed' to reserved words
Bug 29810: Add summary of x-koha-embed header to api spec
Bug 29810: Document x-koha-embed header on patrons endpoints
Bug 29810: Document x-koha-embed header on checkouts endpoints
Bug 29810: Document x-koha-embed header on biblios endpoints
Bug 29810: Document x-koha-embed header on cash registers endpoints
Bug 29810: Document x-koha-embed header on libraries endpoints
Bug 29810: Document x-koha-embed header on orders endpoints
Bug 29810: Add 'x-koha-embed' to reserved words
Bug 29810: Add summary of x-koha-embed header to api spec
Bug 29810: Document x-koha-embed header on patrons endpoints
Bug 29810: Document x-koha-embed header on checkouts endpoints
Bug 29810: Document x-koha-embed header on biblios endpoints
Bug 29810: Document x-koha-embed header on cash registers endpoints
Bug 29810: Document x-koha-embed header on libraries endpoints
Bug 29810: Document x-koha-embed header on orders endpoints
Bug 29810: Add 'x-koha-embed' to reserved words
Bug 29810: Add summary of x-koha-embed header to api spec
Bug 29810: Document x-koha-embed header on patrons endpoints
Bug 29810: Document x-koha-embed header on checkouts endpoints
Bug 29810: Document x-koha-embed header on biblios endpoints
Bug 29810: Document x-koha-embed header on cash registers endpoints
Bug 29810: Document x-koha-embed header on libraries endpoints
Bug 29810: Document x-koha-embed header on orders endpoints
Bug 29810: Add 'x-koha-embed' to reserved words
Bug 29810: Fix patron embed definitions

Description Martin Renvoize (ashimema) 2022-01-06 12:51:43 UTC
The current spec document does not detail how x-koha-embed headers can be used to include related data in queries.
Comment 1 Martin Renvoize (ashimema) 2022-01-06 13:12:46 UTC Comment hidden (obsolete)
Comment 2 Martin Renvoize (ashimema) 2022-01-06 13:12:49 UTC Comment hidden (obsolete)
Comment 3 Martin Renvoize (ashimema) 2022-01-06 13:27:49 UTC Comment hidden (obsolete)
Comment 4 Martin Renvoize (ashimema) 2022-01-06 13:27:52 UTC Comment hidden (obsolete)
Comment 5 Martin Renvoize (ashimema) 2022-01-06 13:27:57 UTC Comment hidden (obsolete)
Comment 6 Martin Renvoize (ashimema) 2022-01-06 13:28:01 UTC Comment hidden (obsolete)
Comment 7 Martin Renvoize (ashimema) 2022-01-06 13:28:04 UTC Comment hidden (obsolete)
Comment 8 Martin Renvoize (ashimema) 2022-01-06 13:28:08 UTC Comment hidden (obsolete)
Comment 9 Martin Renvoize (ashimema) 2022-01-06 13:28:11 UTC Comment hidden (obsolete)
Comment 10 Martin Renvoize (ashimema) 2022-01-07 11:23:51 UTC
Grr.. looks like collectionFormat support requires a newer version of JSON::Validator so this breaks our embeds
Comment 11 Martin Renvoize (ashimema) 2022-03-24 12:37:50 UTC Comment hidden (obsolete)
Comment 12 Martin Renvoize (ashimema) 2022-03-24 12:37:54 UTC Comment hidden (obsolete)
Comment 13 Martin Renvoize (ashimema) 2022-03-24 12:37:57 UTC Comment hidden (obsolete)
Comment 14 Martin Renvoize (ashimema) 2022-03-24 12:38:01 UTC Comment hidden (obsolete)
Comment 15 Martin Renvoize (ashimema) 2022-03-24 12:38:05 UTC Comment hidden (obsolete)
Comment 16 Martin Renvoize (ashimema) 2022-03-24 12:38:09 UTC Comment hidden (obsolete)
Comment 17 Martin Renvoize (ashimema) 2022-03-24 12:38:13 UTC Comment hidden (obsolete)
Comment 18 Martin Renvoize (ashimema) 2022-03-24 12:38:48 UTC
Rebased against bug 30194 and ready for testing again :)
Comment 19 Martin Renvoize (ashimema) 2022-03-24 14:20:21 UTC Comment hidden (obsolete)
Comment 20 Martin Renvoize (ashimema) 2022-03-24 14:20:25 UTC Comment hidden (obsolete)
Comment 21 Martin Renvoize (ashimema) 2022-03-24 14:20:29 UTC Comment hidden (obsolete)
Comment 22 Martin Renvoize (ashimema) 2022-03-24 14:20:33 UTC Comment hidden (obsolete)
Comment 23 Martin Renvoize (ashimema) 2022-03-24 14:20:37 UTC Comment hidden (obsolete)
Comment 24 Martin Renvoize (ashimema) 2022-03-24 14:20:42 UTC Comment hidden (obsolete)
Comment 25 Martin Renvoize (ashimema) 2022-03-24 14:20:47 UTC Comment hidden (obsolete)
Comment 26 Martin Renvoize (ashimema) 2022-03-24 14:20:51 UTC Comment hidden (obsolete)
Comment 27 Martin Renvoize (ashimema) 2022-03-24 14:31:24 UTC
Looks like collectionFormat still isn't working as expected for these headers :(... I've added a slight modification to one of the failing tests in the final patch to highlight the issue..
Comment 28 Martin Renvoize (ashimema) 2022-03-25 11:51:53 UTC
Created attachment 132223 [details] [review]
Bug 29810: Add summary of x-koha-embed header to api spec

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 29 Martin Renvoize (ashimema) 2022-03-25 11:51:57 UTC
Created attachment 132224 [details] [review]
Bug 29810: Document x-koha-embed header on patrons endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 30 Martin Renvoize (ashimema) 2022-03-25 11:52:01 UTC
Created attachment 132225 [details] [review]
Bug 29810: Document x-koha-embed header on checkouts endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 31 Martin Renvoize (ashimema) 2022-03-25 11:52:05 UTC
Created attachment 132226 [details] [review]
Bug 29810: Document x-koha-embed header on biblios endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 32 Martin Renvoize (ashimema) 2022-03-25 11:52:09 UTC
Created attachment 132227 [details] [review]
Bug 29810: Document x-koha-embed header on cash registers endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 33 Martin Renvoize (ashimema) 2022-03-25 11:52:13 UTC
Created attachment 132228 [details] [review]
Bug 29810: Document x-koha-embed header on libraries endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 34 Martin Renvoize (ashimema) 2022-03-25 11:52:17 UTC
Created attachment 132229 [details] [review]
Bug 29810: Document x-koha-embed header on orders endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 35 Martin Renvoize (ashimema) 2022-03-25 11:52:21 UTC
Created attachment 132230 [details] [review]
Bug 29810: Add 'x-koha-embed' to reserved words

The maintainers of Mojolicious::Plugin::OpenAPI and friends fixed the
problem with using collectionFormat for Headers in the upstream library.

However, this highlighted an outstanding issue in our code when I ran
the unit tests. We have not been stripping x-koha-embed at the query
level as it did not exist in the reserved_words list.  This patch
resolves that and gets the acquisitions_orders test passing again.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Comment 36 Martin Renvoize (ashimema) 2022-03-25 11:58:43 UTC
Woopie, this now all works!

This collectionFormat issue I had with headers was quickly fixed upstream with the release of JSON::Validator 5.08 (which also bumped Mojolicious::Plugin::OpenAPI to v5.05).

Could we get those packaged whilst you are in the packaging mindset for these modules Mason?

With that in mind, the test plan is to read the documentation added in the patches and confirm it is current and meaningful. Once you've done that, ensure you have the latest modules at mentioned above (cpanm Mojolicous::Plugin::OpenAPI should do the trick if your testing before it's been packaged) and then run the API test suit.. prove t/db_dependant/api/v1/*.
Comment 37 Tomás Cohen Arazi (tcohen) 2022-03-25 19:44:18 UTC
Created attachment 132255 [details] [review]
Bug 29810: Add summary of x-koha-embed header to api spec

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 38 Tomás Cohen Arazi (tcohen) 2022-03-25 19:44:22 UTC
Created attachment 132256 [details] [review]
Bug 29810: Document x-koha-embed header on patrons endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 39 Tomás Cohen Arazi (tcohen) 2022-03-25 19:44:27 UTC
Created attachment 132257 [details] [review]
Bug 29810: Document x-koha-embed header on checkouts endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 40 Tomás Cohen Arazi (tcohen) 2022-03-25 19:44:32 UTC
Created attachment 132258 [details] [review]
Bug 29810: Document x-koha-embed header on biblios endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 41 Tomás Cohen Arazi (tcohen) 2022-03-25 19:44:36 UTC
Created attachment 132259 [details] [review]
Bug 29810: Document x-koha-embed header on cash registers endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 42 Tomás Cohen Arazi (tcohen) 2022-03-25 19:44:41 UTC
Created attachment 132260 [details] [review]
Bug 29810: Document x-koha-embed header on libraries endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 43 Tomás Cohen Arazi (tcohen) 2022-03-25 19:44:45 UTC
Created attachment 132261 [details] [review]
Bug 29810: Document x-koha-embed header on orders endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 44 Tomás Cohen Arazi (tcohen) 2022-03-25 19:44:50 UTC
Created attachment 132262 [details] [review]
Bug 29810: Add 'x-koha-embed' to reserved words

The maintainers of Mojolicious::Plugin::OpenAPI and friends fixed the
problem with using collectionFormat for Headers in the upstream library.

However, this highlighted an outstanding issue in our code when I ran
the unit tests. We have not been stripping x-koha-embed at the query
level as it did not exist in the reserved_words list.  This patch
resolves that and gets the acquisitions_orders test passing again.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 45 Tomás Cohen Arazi (tcohen) 2022-03-25 19:48:48 UTC
Great work, love where we are headed to.
Comment 46 Jonathan Druart 2022-03-28 14:51:27 UTC
We should have a test and make it a requirement.
Comment 47 Jonathan Druart 2022-03-28 15:02:21 UTC
Created attachment 132341 [details] [review]
Bug 29810: Add summary of x-koha-embed header to api spec

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 48 Jonathan Druart 2022-03-28 15:02:31 UTC
Created attachment 132342 [details] [review]
Bug 29810: Document x-koha-embed header on patrons endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 49 Jonathan Druart 2022-03-28 15:02:38 UTC
Created attachment 132343 [details] [review]
Bug 29810: Document x-koha-embed header on checkouts endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 50 Jonathan Druart 2022-03-28 15:02:45 UTC
Created attachment 132344 [details] [review]
Bug 29810: Document x-koha-embed header on biblios endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 51 Jonathan Druart 2022-03-28 15:02:55 UTC
Created attachment 132345 [details] [review]
Bug 29810: Document x-koha-embed header on cash registers endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 52 Jonathan Druart 2022-03-28 15:03:04 UTC
Created attachment 132346 [details] [review]
Bug 29810: Document x-koha-embed header on libraries endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 53 Jonathan Druart 2022-03-28 15:03:19 UTC
Created attachment 132347 [details] [review]
Bug 29810: Document x-koha-embed header on orders endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 54 Jonathan Druart 2022-03-28 15:03:29 UTC
Created attachment 132348 [details] [review]
Bug 29810: Add 'x-koha-embed' to reserved words

The maintainers of Mojolicious::Plugin::OpenAPI and friends fixed the
problem with using collectionFormat for Headers in the upstream library.

However, this highlighted an outstanding issue in our code when I ran
the unit tests. We have not been stripping x-koha-embed at the query
level as it did not exist in the reserved_words list.  This patch
resolves that and gets the acquisitions_orders test passing again.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 55 Fridolin Somers 2022-04-07 10:06:41 UTC
Sorry does not apply anymore since Bug 30394
Rebase looks easy but i prefer it is done the author ;)
Comment 56 Tomás Cohen Arazi (tcohen) 2022-04-07 10:13:42 UTC
Created attachment 133063 [details] [review]
Bug 29810: Add summary of x-koha-embed header to api spec

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 57 Tomás Cohen Arazi (tcohen) 2022-04-07 10:13:47 UTC
Created attachment 133064 [details] [review]
Bug 29810: Document x-koha-embed header on patrons endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 58 Tomás Cohen Arazi (tcohen) 2022-04-07 10:13:52 UTC
Created attachment 133065 [details] [review]
Bug 29810: Document x-koha-embed header on checkouts endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 59 Tomás Cohen Arazi (tcohen) 2022-04-07 10:13:57 UTC
Created attachment 133066 [details] [review]
Bug 29810: Document x-koha-embed header on biblios endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 60 Tomás Cohen Arazi (tcohen) 2022-04-07 10:14:02 UTC
Created attachment 133067 [details] [review]
Bug 29810: Document x-koha-embed header on cash registers endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 61 Tomás Cohen Arazi (tcohen) 2022-04-07 10:14:07 UTC
Created attachment 133068 [details] [review]
Bug 29810: Document x-koha-embed header on libraries endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 62 Tomás Cohen Arazi (tcohen) 2022-04-07 10:14:12 UTC
Created attachment 133069 [details] [review]
Bug 29810: Document x-koha-embed header on orders endpoints

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 63 Tomás Cohen Arazi (tcohen) 2022-04-07 10:14:17 UTC
Created attachment 133070 [details] [review]
Bug 29810: Add 'x-koha-embed' to reserved words

The maintainers of Mojolicious::Plugin::OpenAPI and friends fixed the
problem with using collectionFormat for Headers in the upstream library.

However, this highlighted an outstanding issue in our code when I ran
the unit tests. We have not been stripping x-koha-embed at the query
level as it did not exist in the reserved_words list.  This patch
resolves that and gets the acquisitions_orders test passing again.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 64 Tomás Cohen Arazi (tcohen) 2022-04-07 10:14:43 UTC
(In reply to Fridolin Somers from comment #55)
> Sorry does not apply anymore since Bug 30394
> Rebase looks easy but i prefer it is done the author ;)

Done :-D
Comment 65 Fridolin Somers 2022-04-12 09:41:30 UTC
Pushed to master for 22.05, thanks to everybody involved ﷐[U+1F984]﷑
Comment 66 Tomás Cohen Arazi (tcohen) 2022-04-13 20:14:26 UTC
Created attachment 133285 [details] [review]
Bug 29810: Fix patron embed definitions

Due to a race and a bad rebase, the patrons embeds added on bug 30063
didn't get copied to the parameters secition, thus breaking embedding.

To test:
1. In master, open the patron search page and the inspector
2. Perform a search
=> FAIL: No results
=> FAIL: There's an error 500 in the API response, mentioning embedding
is not allowed
3. Apply this patch
4. Restart all
6. Repeat 2
=> SUCCESS: Results are back!
=> SUCCESS: No more API errors
7. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 67 Martin Renvoize (ashimema) 2022-04-14 10:49:11 UTC
*** Bug 30537 has been marked as a duplicate of this bug. ***
Comment 68 Martin Renvoize (ashimema) 2022-04-14 10:49:38 UTC
Follow-up pushed as RM assistant to get people back up and running. :)