[Bug 42869] New: Add REST API coding guideline for async job endpoints (202 Accepted)
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Bug ID: 42869 Summary: Add REST API coding guideline for async job endpoints (202 Accepted) Initiative type: --- Sponsorship --- status: Product: Koha Version: Main Hardware: All OS: All Status: NEW Severity: enhancement Priority: P5 - low Component: REST API Assignee: koha-bugs@lists.koha-community.org Reporter: tomascohen@gmail.com QA Contact: testopia@bugs.koha-community.org CC: tomascohen@gmail.com Target Milestone: --- Koha currently has several REST API endpoints that enqueue background jobs and return a job_id. These endpoints incorrectly use HTTP 201 Created, which implies a resource was durably created and is immediately addressable. Per HTTP semantics, endpoints that accept a request for asynchronous processing should return 202 Accepted with a Location header pointing to the job tracking endpoint (/api/v1/jobs/{job_id}). Affected endpoints: - POST /api/v1/erm/eholdings/local/titles/import_from_list (returns 201) - POST /api/v1/erm/eholdings/local/titles/import_from_kbart_file (returns 201) - POST /api/v1/cover_images/batch (fixed in bug 42404) This bug tracks: 1. Adding REST3.2.1.2 to the coding guidelines wiki 2. Updating existing endpoints to comply See also: Bug 42404 Wiki page: https://wiki.koha-community.org/wiki/Coding_Guidelines_-_API#REST3.4.1_POST -- You are receiving this mail because: You are watching all bug changes. You are the assignee for the bug.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- GIT URL| |42404 Assignee|koha-bugs@lists.koha-commun |tomascohen@gmail.com |ity.org | Status|NEW |ASSIGNED Summary|Add REST API coding |Adjust async job endpoints |guideline for async job |to coding guideline (202 |endpoints (202 Accepted) |Accepted) -- You are receiving this mail because: You are the assignee for the bug. You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- URL| |https://wiki.koha-community | |.org/wiki/Coding_Guidelines | |_-_API#.5BDRAFT.5D_REST3.2. | |1.2_POST_.28async_job.29 -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|ASSIGNED |Needs Signoff Patch complexity|--- |Trivial patch -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 --- Comment #1 from Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> --- Created attachment 200612 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=200612&action=edit Bug 42869: Return 202 Accepted for ERM async job endpoints The ERM import endpoints (import_from_list, import_from_kbart_file) enqueue background jobs but incorrectly returned 201 Created. This patch changes them to return 202 Accepted with a Location header pointing to the job tracking endpoint, per HTTP semantics for async operations. Changes: - import_from_list returns 202 with Location: /api/v1/jobs/{job_id} - import_from_kbart_file returns 202 with Location: /api/v1/jobs/{job_id} - OpenAPI spec updated to document 202 responses and Location header - API test updated to assert 202 and Location header - Cypress mock updated to use 202 Test plan: 1. Apply patch 2. Run: $ ktd --shell k$ prove t/db_dependent/api/v1/erm_eholdings_titles.t => SUCCESS: Tests pass! 3. Run Cypress tests: k$ yarn cypress run --spec t/cypress/integration/ERM/Titles_spec.ts => SUCCESS: Tests pass! 4. Sign off :-D -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Patch complexity|Trivial patch |Small patch -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Attachment #200612|0 |1 is obsolete| | -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 --- Comment #2 from Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> --- Created attachment 200645 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=200645&action=edit Bug 42869: Return 202 Accepted for ERM async job endpoints The ERM import endpoints (import_from_list, import_from_kbart_file) enqueue background jobs but incorrectly returned 201 Created. This patch changes them to return 202 Accepted with a Location header pointing to the job tracking endpoint, per HTTP semantics for async operations. Changes: - import_from_list returns 202 with Location: /api/v1/jobs/{job_id} - import_from_kbart_file returns 202 with Location: /api/v1/jobs/{job_id} - OpenAPI spec updated to document 202 responses and Location header - API test updated to assert 202 and Location header - Cypress mock updated to use 202 Test plan: 1. Apply patch 2. Run: $ ktd --shell k$ prove t/db_dependent/api/v1/erm_eholdings_titles.t => SUCCESS: Tests pass! 3. Run Cypress tests: k$ yarn cypress run --spec t/cypress/integration/ERM/Titles_spec.ts => SUCCESS: Tests pass! 4. Sign off :-D -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 --- Comment #3 from Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> --- Created attachment 200646 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=200646&action=edit Bug 42869: (follow-up) Add render_job_accepted helper This patch adds a render_job_accepted($job) helper to the Koha::REST::Plugin::Responses plugin. It takes a Koha::BackgroundJob object, sets the Location header to the job tracking URL, and renders 202 Accepted with the full job representation via $c->objects->to_api. This mirrors the existing render_resource_deleted and render_resource_not_found helpers and makes the coding guideline (REST3.2.1.2) trivially enforceable. Changes: - Add render_job_accepted helper to Koha::REST::Plugin::Responses - Refactor CoverImages and ERM import_from_list to use the helper - ERM import_from_kbart_file keeps explicit render (non-standard body) - Response body is now the full job object (callers still get job_id) - OpenAPI specs reference the job definition for 202 responses - Add unit test for the helper in responses.t Test plan: 1. Apply patch 2. Run: $ ktd --shell k$ prove t/db_dependent/api/v1/responses.t => SUCCESS: Tests pass! k$ prove t/db_dependent/api/v1/cover_images.t => SUCCESS: Tests pass! k$ prove t/db_dependent/api/v1/erm_eholdings_titles.t => SUCCESS: Tests pass! 3. Sign off :-D -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |kyle@bywatersolutions.com, | |martin.renvoize@openfifth.c | |o.uk -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Tomás Cohen Arazi (tcohen) <tomascohen@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- GIT URL|42404 | Depends on| |42404 Referenced Bugs: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42404 [Bug 42404] Add a batch cover images upload endpoint -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 Martin Renvoize (ashimema) <martin.renvoize@openfifth.co.uk> changed: What |Removed |Added ---------------------------------------------------------------------------- QA Contact|testopia@bugs.koha-communit |martin.renvoize@openfifth.c |y.org |o.uk -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 David Nind <david@davidnind.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Status|Needs Signoff |Signed Off -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 David Nind <david@davidnind.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Attachment #200645|0 |1 is obsolete| | Attachment #200646|0 |1 is obsolete| | -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 --- Comment #4 from David Nind <david@davidnind.com> --- Created attachment 201141 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=201141&action=edit Bug 42869: Return 202 Accepted for ERM async job endpoints The ERM import endpoints (import_from_list, import_from_kbart_file) enqueue background jobs but incorrectly returned 201 Created. This patch changes them to return 202 Accepted with a Location header pointing to the job tracking endpoint, per HTTP semantics for async operations. Changes: - import_from_list returns 202 with Location: /api/v1/jobs/{job_id} - import_from_kbart_file returns 202 with Location: /api/v1/jobs/{job_id} - OpenAPI spec updated to document 202 responses and Location header - API test updated to assert 202 and Location header - Cypress mock updated to use 202 Test plan: 1. Apply patch 2. Run: $ ktd --shell k$ prove t/db_dependent/api/v1/erm_eholdings_titles.t => SUCCESS: Tests pass! 3. Run Cypress tests: k$ yarn cypress run --spec t/cypress/integration/ERM/Titles_spec.ts => SUCCESS: Tests pass! 4. Sign off :-D Signed-off-by: David Nind <david@davidnind.com> -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=42869 --- Comment #5 from David Nind <david@davidnind.com> --- Created attachment 201142 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=201142&action=edit Bug 42869: (follow-up) Add render_job_accepted helper This patch adds a render_job_accepted($job) helper to the Koha::REST::Plugin::Responses plugin. It takes a Koha::BackgroundJob object, sets the Location header to the job tracking URL, and renders 202 Accepted with the full job representation via $c->objects->to_api. This mirrors the existing render_resource_deleted and render_resource_not_found helpers and makes the coding guideline (REST3.2.1.2) trivially enforceable. Changes: - Add render_job_accepted helper to Koha::REST::Plugin::Responses - Refactor CoverImages and ERM import_from_list to use the helper - ERM import_from_kbart_file keeps explicit render (non-standard body) - Response body is now the full job object (callers still get job_id) - OpenAPI specs reference the job definition for 202 responses - Add unit test for the helper in responses.t Test plan: 1. Apply patch 2. Run: $ ktd --shell k$ prove t/db_dependent/api/v1/responses.t => SUCCESS: Tests pass! k$ prove t/db_dependent/api/v1/cover_images.t => SUCCESS: Tests pass! k$ prove t/db_dependent/api/v1/erm_eholdings_titles.t => SUCCESS: Tests pass! 3. Sign off :-D Signed-off-by: David Nind <david@davidnind.com> -- You are receiving this mail because: You are watching all bug changes.
participants (1)
-
bugzilla-daemon＠bugs.koha-community.org