Bug 41463 - Add Koha REST API endpoints for OAI sets
Summary: Add Koha REST API endpoints for OAI sets
Status: Needs Signoff
Alias: None
Product: Koha
Classification: Unclassified
Component: REST API (show other bugs)
Version: unspecified
Hardware: All All
: P5 - low enhancement
Assignee: Aleisha Amohia
QA Contact: Testopia
URL:
Keywords:
Depends on: 41462
Blocks:
  Show dependency treegraph
 
Reported: 2025-12-17 01:44 UTC by Aleisha Amohia
Modified: 2025-12-19 02:22 UTC (History)
2 users (show)

See Also:
GIT URL:
Initiative type: ---
Sponsorship status: Sponsored
Comma delimited list of Sponsors:
Crowdfunding goal: 0
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:
Circulation function:


Attachments
Bug 41463: [WIP] oai_sets REST API endpoint (5.19 KB, patch)
2025-12-17 04:00 UTC, Aleisha Amohia
Details | Diff | Splinter Review
Bug 41463: [WIP] oai_sets REST API endpoint (10.05 KB, patch)
2025-12-18 03:53 UTC, Aleisha Amohia
Details | Diff | Splinter Review
Bug 41463: REST API endpoint to gain information about an OAI set (14.14 KB, patch)
2025-12-19 01:03 UTC, Aleisha Amohia
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Aleisha Amohia 2025-12-17 01:44:19 UTC

    
Comment 1 Aleisha Amohia 2025-12-17 04:00:42 UTC
Created attachment 190565 [details] [review]
Bug 41463: [WIP] oai_sets REST API endpoint
Comment 2 Aleisha Amohia 2025-12-18 03:53:01 UTC
Created attachment 190610 [details] [review]
Bug 41463: [WIP] oai_sets REST API endpoint
Comment 3 Aleisha Amohia 2025-12-19 01:03:40 UTC
Created attachment 190631 [details] [review]
Bug 41463: REST API endpoint to gain information about an OAI set

This API endpoint is to be used like:

"/api/v1/oai_sets/{set_id}"

and shows the following information about an OAI set:

- set name
- set spec
- set ID
- total count of items in the set
- count of items in the set which also exist in the catalogue - this is useful for determining how many items have been deleted from the catalogue but has not yet been reflected in the OAI set

To test:

1. Apply the patch and rebuild resources for the new API endpoints to take effect, then restart services. In KTD this looks like:

perl ./build-resources.PL
yarn api:bundle
restart_all

2. Confirm the new getOAISet definition is available to the API: OPAC-URL/api/v1/.html

3. In the staff interface, go to Koha administration -> OAI sets configuration and create a new set. Give it a spec and name then Save. Go to edit mappings and add the following rule, then Save:

- Field: 942
- Subfield: n
- Operator: not equal to
- Value: 1

(This would essentially exclude items from the set that are OPAC suppressed)

4. Search for a record and edit it. Go to tab 9 to find tag 942 and set n to "No". Saving the record will add it to the OAI set.

5. Now we need to add some items to the set that don't match biblios in the catalogue. The easiest way to do this is by directly adding fake items to the set in the database, something like this:

sudo koha-mysql kohadev
insert into oai_sets_biblios (biblionumber, set_id) values (12345678, 1);
insert into oai_sets_biblios (biblionumber, set_id) values (123456378, 1);
insert into oai_sets_biblios (biblionumber, set_id) values (12345678, 1);

So we now have 4 items in the set - 1 that matches an existing biblio in the catalogue, and 3 that don't (in practise, they may have existed once, but have since been deleted and the set hasn't harvested those deletions).

6. Go to the API endpoint for your set and confirm the correction information is fetched: OPAC-URL/api/v1/oai_sets/{set_id}

7. Confirm tests pass:

prove t/db_dependent/OAI/Sets.t
prove t/db_dependent/api/v1/oai_sets.t

Sponsored-by: Auckland University of Technology
Comment 4 David Nind 2025-12-19 02:17:15 UTC
Not sure what the expected result from steps 5 and 6 is - I only get 3 items in the set.

Should the record edited in step 4 be included in the result?

Testing notes (using KTD):

1. When adding the third item in step 5 I get:
     insert into oai_sets_biblios (biblionumber, set_id) values (12345678, 1);
     ERROR 1062 (23000): Duplicate entry '12345678-1' for key 'PRIMARY'

2. I can add a third item to the set if I make it unique:
     insert into oai_sets_biblios (biblionumber, set_id) values (123456789, 1);
     Query OK, 1 row affected (0.003 sec)

3. If I select everything from the table, I only get three rows:
     select * from oai_sets_biblios;
     +--------------+--------+
     | biblionumber | set_id |
     +--------------+--------+
     |     12345678 |      1 |
     |    123456378 |      1 |
     |    123456789 |      1 |
     +--------------+--------+
     3 rows in set (0.000 sec)

4. The results from /api/v1/oai_sets/1 for step 6 is:

    {
      "catalog_count": 1,
      "name": "A",
      "set_id": 1,
      "spec": "A",
      "total_count": 3
    }
Comment 5 Aleisha Amohia 2025-12-19 02:22:12 UTC
(In reply to David Nind from comment #4)
> Not sure what the expected result from steps 5 and 6 is - I only get 3 items
> in the set.
> 
> Should the record edited in step 4 be included in the result?

Yes it should - when I edited the record, it was added to the OAI set automatically. Maybe some other setting is also needed for that to happen for you...

> 
> Testing notes (using KTD):
> 
> 1. When adding the third item in step 5 I get:
>      insert into oai_sets_biblios (biblionumber, set_id) values (12345678,
> 1);
>      ERROR 1062 (23000): Duplicate entry '12345678-1' for key 'PRIMARY'

Oops sorry bad copy paste in my test plan!

> 
> 2. I can add a third item to the set if I make it unique:
>      insert into oai_sets_biblios (biblionumber, set_id) values (123456789,
> 1);
>      Query OK, 1 row affected (0.003 sec)
> 
> 3. If I select everything from the table, I only get three rows:
>      select * from oai_sets_biblios;
>      +--------------+--------+
>      | biblionumber | set_id |
>      +--------------+--------+
>      |     12345678 |      1 |
>      |    123456378 |      1 |
>      |    123456789 |      1 |
>      +--------------+--------+
>      3 rows in set (0.000 sec)
> 
> 4. The results from /api/v1/oai_sets/1 for step 6 is:
> 
>     {
>       "catalog_count": 1,
>       "name": "A",
>       "set_id": 1,
>       "spec": "A",
>       "total_count": 3
>     }