Bug 41463

Summary: Add Koha REST API endpoints for OAI sets
Product: Koha Reporter: Aleisha Amohia <aleisha>
Component: REST APIAssignee: Aleisha Amohia <aleisha>
Status: Needs Signoff --- QA Contact: Testopia <testopia>
Severity: enhancement    
Priority: P5 - low CC: david, tomascohen
Version: unspecified   
Hardware: All   
OS: All   
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:
Bug Depends on: 41462    
Bug Blocks:    
Attachments: Bug 41463: [WIP] oai_sets REST API endpoint
Bug 41463: [WIP] oai_sets REST API endpoint
Bug 41463: REST API endpoint to gain information about an OAI set

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
>     }