RFC RESTapi needed for folio interaction

From Koha Wiki
Jump to navigation Jump to search

A Koha RFC that documents Koha REST API or other sub-system enhancements that would aid FOLIO integration. Published as an RFC to https://wiki.koha-community.org/wiki/Category:RFCs for public review and validation from community stakeholders with a goal to be an agenda item at the March 20 2017 Marseilles Koha Hackfest.

Proposing to address REST apis that would be useful for Koha to have extended for interaction with FOLIO project. Ideally we can do this in different stages. Stage 1 would be actions - like Circulation / Patron management / Course reserves. Stage 2 would be sharing Bibliographic Data with Folio (this could be both directions - harvesting data from Folio). Stage 3 would be reporting - Koha will need RESTapis so you can get report information from Folio for display and use in Koha reporting system (very useful for discovery reports - electronic datas)

Example 1: Circulation

Ideally a Koha Circulation Module would need to be created in Folio for Circulation, Borrower management and Requesting (holds). Module would contain Module UI and App Module. Service section of Module would provide RESTapis calls to Koha and pass to Okapi Gateway with JSON metadata. For a Circulation APP in Folio we would not want to create all aspects of Koha circulation. Mainly we want to do quick actions natively in Folio while interacting with other modules/Apps.

Suggested needed endpoints in Koha…


  • Patrons :

GET /patrons/ (Get all the patrons)

GET /patrons/{patrons_id} (Get the specified patron)

PUT /patrons/{patrons_id} (Update patron information)

POST /patrons/ (Add a new patron)

DELETE /patrons/{patrons_id} (Delete the specified patron)


  • Circulation : Checkouts / Renewals / Checkins:

GET /patrons/{patrons_id}/checkouts (Given a patron id - get all of the patrons checkouts)

GET /patrons/{patrons_id}/checkouts/{checkouts_id} (Given a patron id - get an identified checkouts)

GET /patrons/{patrons_id}/checkouts/{checkouts_id}/renew (Given a patron id and a checkouts_id - get all of the renewals)

PUT /circulation/checkin/ (Return an item)

POST /circulation/checkouts/ (Create a new checkout - needed infos - patrons/items{barcode})

POST


  • Holds:

GET /patrons/{patrons_id}/holds (Get all the holds this patron has)

GET /patrons/{patrons_id}/holds/{holds_id} (Get the identified hold)


  • Accountlines:

GET /patrons/{patrons_id}/accountlines (Get all of the accountlines)

GET /patrons/{patrons_id}/accountlines/{accountlines_id}


  • Messages:

GET /patrons/{patrons_id}/messages (Get all messages and notices for that patrons_id)

GET /patrons/{patrons_id}/messages/{messages_id} (Get an individual messages or notices)

  • Note* must include all definitions - in api/v1/definitions/* and all unit tests t/db_dependent/api/v1/* for above apis


Example 2: Course reserves

Another Module (App and UI) for Course Reserves Management in Folio. Using the bases of a physical collection of materials in Koha (class, material, course informations) harvested and displayed in App UI for Folio - while also adding in materials from electronic materials that are in Folio (discovery materials, ERM - anything stored in the Folio metadata collection).  This one has a more complete end to end endpoints thought out.

  • Endpoints needed:

<NOTE - need to think about ‘enabled’ or ‘disabled’ courses >

GET /courses (Get ALL courses)

GET /courses/{course_id} (Get one course)

GET /courses/{course_id}/items (Given a course_id, get ALL the items)

GET /courses/{course_id}/items/{item_id} (Given a course_id, get the item identified by item_id)

PUT /courses/{course_id} (Update information of the identified course - This will be useful to ‘disable’ course) PUT /courses/{course_id}/course_item/{item_id} (Update an item in an identified course)

POST /courses/ (New Courses with all infos) POST /courses/{course_id}/course_reserve/ (New reserves added to course)

DELETE /courses/{course_id} DELETE /courses/{course_id}/item/{item_id}

  • Note* must include all definitions - in api/v1/definitions/* and all unit tests t/db_dependent/api/v1/* for above apis


Stage 2: Sharing Bibliographic Information

Not completely necessary to have a App Module in Folio - should be able to share this information directly with Stripes (UI) and Stripes-Okapi for communication and storage through Okapi-Gateway.  Could use OAI-PMH stuff, or FOLIO could talk to the Elastic cluster itself.  (We would need a filter on any DELETE directly to the ES cluster - or wrap that in an AUTH endpoint to just pass through)

GET /auth/

GET /auth/{auth_id}/es_index

  • Note* must include all definitions - in api/v1/definitions/* and all unit tests t/db_dependent/api/v1/* for above apis


Stage 3: Getting statistical informations from Folio. For example having reports of digital and electronic usage from Folio to add to statistical reports in Koha. Having lovely usage statistics on combination of physical and digital usage. No Folio module (app) needed here


  • Reports:

GET /reports (GET all the reports) GET /reports/{reports_id}

PUT /reports/{reports_id}

POST /reports

DELETE /reports/{reports_id}


Koha/REST/V1/Reports.pm Note* must include all definitions - in api/v1/definitions/* and all unit tests t/db_dependent/api/v1/* for above apis


Some notes about Folio: All Data passed to modules must be JSON schema. CRUD RAML - RESTapi module language. All modules must register with the Gateway. Gateway proxies all requests. RAML v 0.8


  • The plan is to use this document as an example for creating a common use of terms for the endpoints. One Example is patrons - We have many different terms for the same thing - but to the outside - “anyone” consuming the api - doesn’t matter it should be one term (patrons). Suggestions have been made to follow what is already labeled in the GUI for Koha but I really want to make sure that we agree upon a common language choice and get that into the coding guidelines. That should become an agenda item for the next dev-meeting and decided on for QA (and developers - if this has already happened pardon me for missing it ;) ). This should be used as a first shot at some common use language but it could be easy to identify any areas that we use different terms for same datas (I don’t feel this should be based off the database tables names - but that is just my thought - IE I am open for discussion - I know this is somewhere else on the wiki and has been dicussed - I couldn't find it when searching for it :) ) .
Retrieved from "https://wiki.koha-community.org/w/index.php?title=RFC_RESTapi_needed_for_folio_interaction&oldid=18318"