Bug 39900 - Add public REST endpoint for additional_contents
Summary: Add public REST endpoint for additional_contents
Status: Needs documenting
Alias: None
Product: Koha
Classification: Unclassified
Component: REST API (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement
Assignee: Pedro Amorim
QA Contact: Marcel de Rooy
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2025-05-14 12:32 UTC by Pedro Amorim
Modified: 2025-10-10 12:08 UTC (History)
8 users (show)

See Also:
GIT URL:
Initiative type: ---
Sponsorship status: ---
Crowdfunding goal: 0
Patch complexity: Small patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
A new public REST API endpoint has been added for retrieving additional contents (news items and HTML customisations) without authentication. This enables external applications and websites to access and display Koha news and custom content. **Endpoint details:** - **Path:** `/api/v1/public/additional_contents` - **Method:** GET - **Authentication:** None required (public endpoint) - **Query parameters:** - Standard search and filter parameters for finding specific content - `lang`: Filter by language code to retrieve content in a specific language - `embed`: Use `translated_contents` to include all available translations **Key features:** - **Public access**: No authentication required, making it suitable for displaying library news on external websites - **Multi-language support**: Retrieve content in specific languages or fetch all translations at once using the `translated_contents` embed - **Flexible filtering**: Search and filter additional contents using standard API query parameters - **Content types**: Access both news items and HTML customisations through the same endpoint **For developers:** This endpoint follows the same patterns as other Koha public API endpoints. Use the `lang` parameter to retrieve content for a specific language, or use `embed=translated_contents` to get all available translations in a single request. This is particularly useful for multi-lingual library websites that need to display Koha news items. **Example use cases:** - Displaying library news on an external website - Integrating OPAC announcements into a library portal - Building mobile applications that show library notices - Creating custom displays of library information
Version(s) released in:
25.11.00,25.05.04
Circulation function:


Attachments
Bug 39900: Preparation: Refactor public_query_search_params for reusability (3.00 KB, patch)
2025-05-14 12:41 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: Preparation: Move html customizations options to class for reusability (4.61 KB, patch)
2025-05-14 12:41 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: REST API specs and class changes (8.56 KB, patch)
2025-05-14 12:41 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: Add translated_contents embed (2.36 KB, patch)
2025-05-14 12:41 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: Add tests (3.72 KB, patch)
2025-05-14 12:41 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: Preparation: Refactor public_query_search_params for reusability (3.04 KB, patch)
2025-06-01 20:07 UTC, David Nind
Details | Diff | Splinter Review
Bug 39900: Preparation: Move html customizations options to class for reusability (4.65 KB, patch)
2025-06-01 20:07 UTC, David Nind
Details | Diff | Splinter Review
Bug 39900: REST API specs and class changes (8.60 KB, patch)
2025-06-01 20:07 UTC, David Nind
Details | Diff | Splinter Review
Bug 39900: Add translated_contents embed (2.40 KB, patch)
2025-06-01 20:08 UTC, David Nind
Details | Diff | Splinter Review
Bug 39900: Add tests (3.76 KB, patch)
2025-06-01 20:08 UTC, David Nind
Details | Diff | Splinter Review
Bug 39900: Preparation: Refactor public_query_search_params for reusability (3.04 KB, patch)
2025-07-28 08:47 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: Preparation: Move html customizations options to class for reusability (4.71 KB, patch)
2025-07-28 08:47 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: REST API specs and class changes (8.61 KB, patch)
2025-07-28 08:47 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: Add translated_contents embed (2.41 KB, patch)
2025-07-28 08:47 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: Add tests (3.77 KB, patch)
2025-07-28 08:47 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: (QA follow-up): Add translated_contents to tests (4.33 KB, patch)
2025-08-01 10:53 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: (QA follow-up): Add translated_contents to tests (4.19 KB, patch)
2025-08-01 10:54 UTC, Pedro Amorim
Details | Diff | Splinter Review
Bug 39900: Preparation: Refactor public_query_search_params for reusability (3.14 KB, patch)
2025-08-04 08:16 UTC, Marcel de Rooy
Details | Diff | Splinter Review
Bug 39900: Preparation: Move html customizations options to class for reusability (4.80 KB, patch)
2025-08-04 08:16 UTC, Marcel de Rooy
Details | Diff | Splinter Review
Bug 39900: REST API specs and class changes (8.70 KB, patch)
2025-08-04 08:16 UTC, Marcel de Rooy
Details | Diff | Splinter Review
Bug 39900: Add translated_contents embed (2.50 KB, patch)
2025-08-04 08:17 UTC, Marcel de Rooy
Details | Diff | Splinter Review
Bug 39900: Add tests (3.86 KB, patch)
2025-08-04 08:17 UTC, Marcel de Rooy
Details | Diff | Splinter Review
Bug 39900: (QA follow-up): Add translated_contents to tests (4.29 KB, patch)
2025-08-04 08:17 UTC, Marcel de Rooy
Details | Diff | Splinter Review
Bug 39900: (QA follow-up) Add missing tag description (960 bytes, patch)
2025-08-15 14:13 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 39900: (follow-up) Add a newline to end of additional_contents.yaml (828 bytes, patch)
2025-08-15 14:50 UTC, Lucas Gass (lukeg)
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Pedro Amorim 2025-05-14 12:32:56 UTC

    
Comment 1 Pedro Amorim 2025-05-14 12:41:40 UTC Comment hidden (obsolete)
Comment 2 Pedro Amorim 2025-05-14 12:41:43 UTC Comment hidden (obsolete)
Comment 3 Pedro Amorim 2025-05-14 12:41:46 UTC Comment hidden (obsolete)
Comment 4 Pedro Amorim 2025-05-14 12:41:48 UTC Comment hidden (obsolete)
Comment 5 Pedro Amorim 2025-05-14 12:41:51 UTC Comment hidden (obsolete)
Comment 6 David Nind 2025-06-01 20:07:49 UTC
Created attachment 182887 [details] [review]
Bug 39900: Preparation: Refactor public_query_search_params for reusability

Ensure no regressions are introduced, run:
prove t/db_dependent/Koha/AdditionalContents.t

Signed-off-by: David Nind <david@davidnind.com>
Comment 7 David Nind 2025-06-01 20:07:52 UTC
Created attachment 182888 [details] [review]
Bug 39900: Preparation: Move html customizations options to class for reusability

Signed-off-by: David Nind <david@davidnind.com>
Comment 8 David Nind 2025-06-01 20:07:55 UTC
Created attachment 182889 [details] [review]
Bug 39900: REST API specs and class changes

Signed-off-by: David Nind <david@davidnind.com>
Comment 9 David Nind 2025-06-01 20:08:01 UTC
Created attachment 182890 [details] [review]
Bug 39900: Add translated_contents embed

Signed-off-by: David Nind <david@davidnind.com>
Comment 10 David Nind 2025-06-01 20:08:16 UTC
Created attachment 182891 [details] [review]
Bug 39900: Add tests

prove t/db_dependent/api/v1/additional_contents.t

Signed-off-by: David Nind <david@davidnind.com>
Comment 11 David Nind 2025-06-01 20:11:29 UTC
I tested by running the tests. If this is insufficient, please change the status back to needs signoff.

Testing notes (using KTD):
1. Apply the patches.
2. Rebuild everything (not sure that this step is required): yarn build
3. Ran the tests and these passed:
   - prove t/db_dependent/Koha/AdditionalContents.t
   - prove t/db_dependent/api/v1/additional_contents.t
Comment 12 Marcel de Rooy 2025-07-17 09:32:45 UTC
Applying: Bug 39900: Preparation: Move html customizations options to class for reusability
error: sha1 information is lacking or useless (Koha/AdditionalContents.pm).
error: could not build fake ancestor
Comment 13 Pedro Amorim 2025-07-28 08:47:23 UTC
Created attachment 184722 [details] [review]
Bug 39900: Preparation: Refactor public_query_search_params for reusability

Ensure no regressions are introduced, run:
prove t/db_dependent/Koha/AdditionalContents.t

Signed-off-by: David Nind <david@davidnind.com>
Comment 14 Pedro Amorim 2025-07-28 08:47:25 UTC
Created attachment 184723 [details] [review]
Bug 39900: Preparation: Move html customizations options to class for reusability

Signed-off-by: David Nind <david@davidnind.com>
Comment 15 Pedro Amorim 2025-07-28 08:47:27 UTC
Created attachment 184724 [details] [review]
Bug 39900: REST API specs and class changes

Signed-off-by: David Nind <david@davidnind.com>
Comment 16 Pedro Amorim 2025-07-28 08:47:30 UTC
Created attachment 184725 [details] [review]
Bug 39900: Add translated_contents embed

Signed-off-by: David Nind <david@davidnind.com>
Comment 17 Pedro Amorim 2025-07-28 08:47:32 UTC
Created attachment 184726 [details] [review]
Bug 39900: Add tests

prove t/db_dependent/api/v1/additional_contents.t

Signed-off-by: David Nind <david@davidnind.com>
Comment 18 Marcel de Rooy 2025-08-01 06:28:48 UTC
Looking here
Comment 19 Marcel de Rooy 2025-08-01 07:09:21 UTC
Looks good to me. Two questions remaining:

[1] The test with the translation embed should imo contain some translation data. Now we are just comparing empty arrays. So add two translations to Localizations.

[2] What I am actually missing is the possibility to ask for a specific translation by passing a language code. Now translated_contents just contains everything and the receiver should open all elements to check the language.

Changing status to reflect need for feedback.
Comment 20 Pedro Amorim 2025-08-01 10:53:18 UTC Comment hidden (obsolete)
Comment 21 Pedro Amorim 2025-08-01 10:54:27 UTC
Created attachment 184979 [details] [review]
Bug 39900: (QA follow-up): Add translated_contents to tests

Also add tests to searching for specific language code

prove t/db_dependent/api/v1/additional_contents.t
Comment 22 Marcel de Rooy 2025-08-04 08:16:55 UTC
Created attachment 185081 [details] [review]
Bug 39900: Preparation: Refactor public_query_search_params for reusability

Ensure no regressions are introduced, run:
prove t/db_dependent/Koha/AdditionalContents.t

Signed-off-by: David Nind <david@davidnind.com>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 23 Marcel de Rooy 2025-08-04 08:16:57 UTC
Created attachment 185082 [details] [review]
Bug 39900: Preparation: Move html customizations options to class for reusability

Signed-off-by: David Nind <david@davidnind.com>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 24 Marcel de Rooy 2025-08-04 08:16:59 UTC
Created attachment 185083 [details] [review]
Bug 39900: REST API specs and class changes

Signed-off-by: David Nind <david@davidnind.com>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 25 Marcel de Rooy 2025-08-04 08:17:01 UTC
Created attachment 185084 [details] [review]
Bug 39900: Add translated_contents embed

Signed-off-by: David Nind <david@davidnind.com>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 26 Marcel de Rooy 2025-08-04 08:17:03 UTC
Created attachment 185085 [details] [review]
Bug 39900: Add tests

prove t/db_dependent/api/v1/additional_contents.t

Signed-off-by: David Nind <david@davidnind.com>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 27 Marcel de Rooy 2025-08-04 08:17:06 UTC
Created attachment 185086 [details] [review]
Bug 39900: (QA follow-up): Add translated_contents to tests

Also add tests to searching for specific language code

prove t/db_dependent/api/v1/additional_contents.t

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
Comment 28 Lucas Gass (lukeg) 2025-08-14 22:09:12 UTC
Nice work everyone!

Pushed to main for 25.11
Comment 29 Lucas Gass (lukeg) 2025-08-14 22:11:01 UTC
Can you please add release notes?
Comment 30 Lucas Gass (lukeg) 2025-08-15 13:42:03 UTC
There are a few failures due to this bug, I think: 

xt/api.t is failing:

    #   Failed test 'No tag errors in the spec'
    #   at /kohadevbox/koha/xt/api.t line 128.
    #     Structures begin differing at:
    #          $got->[0] = 'get /public/additional_contents -> uses tag 'additional_contents' not present in top level list'
    #     $expected->[0] = Does not exist
get /public/additional_contents -> uses tag 'additional_contents' not present in top level list
    # Looks like you failed 1 test of 1.
not ok 4 - tags tests



And also:

xt_find_missing_new_lines_at_the_end_of_file_t.api/v1/swagger/paths/additional_contents.yaml should end with a new line (504)
Comment 31 Tomás Cohen Arazi (tcohen) 2025-08-15 14:13:14 UTC
Created attachment 185453 [details] [review]
Bug 39900: (QA follow-up) Add missing tag description

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 32 Lucas Gass (lukeg) 2025-08-15 14:50:00 UTC
Created attachment 185455 [details] [review]
Bug 39900: (follow-up) Add a newline to end of additional_contents.yaml
Comment 33 Lucas Gass (lukeg) 2025-08-15 15:53:21 UTC
follow-up's pushed to main
Comment 34 Paul Derscheid 2025-09-20 08:57:57 UTC
Nice work everyone!

Pushed to 25.05.x
Comment 35 Fridolin Somers 2025-10-10 12:08:31 UTC
Enhancement not pushed to 24.11.x