https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=38226 --- Comment #15 from David Cook <dcook@prosentient.com.au> --- (In reply to Tomás Cohen Arazi (tcohen) from comment #11)
Hi all. I picked the RPC keyword only because I wanted a namespace that makes it clear that endpoints defined in it are not RESTful.
I don't see an issue with having a non-RESTful portion of the API for special uses (I'm actually 100% onboard with that), as not everything falls into the CRUD pattern. As an example of this, I'm sure we shouldn't be using the CRUD endpoints for displaying dropdowns. It makes endpoints permissions requirements a real mess e.g. why do you need to access the full library objects in order to display a list of library code/name? Library information is *almost* trivial and not important, but think of other resources.
In another context I proposed we made this batch-like endpoints just be `POST /jobs` (or `POST /jobs/batch_cancel_holds`) and this could be better case here. We just need a pattern to follow.
That said, the 'RPC nature' on this two introduced endpoints is the fact there's a verb in the path: 'populate_empty_callnumbers'.
This particular endpoint is self-documented so I assume Jonathan refers to the guidelines this time. I agree we should document it, if we decide to go this path. As I said, I'd prefer some sort of `POST /jobs` but it would require the consumer to retrieve the job results, etc. Unless we use a pseudo job that (i.e. nothing is queued, etc).
I've found the thread on Mattermost quite interesting! Based on this comment of yours, I think that you and I have come to the same conclusion, which is that it boils down to 3 choices: 1. Try to force things into REST semantics (e.g. POST /jobs or POST /jobs/batch_populate_empty_callnumbers or PUT /batch_record_modification with parameters in POSTDATA) 2. Extend/hybridize REST endpoints with actions in the path (e.g. POST /api/v1/biblios/{biblio_id}/items/populate_empty_callnumbers) 3. Create a RPC endpoint (POST /api/v1/rpc/biblios/{biblio_id}/items/populate_empty_callnumbers or POST /api/v1/rpc with parameters in POSTDATA) #NOTE: I think that gRPC uses paths but JSON-RPC does not use paths. Depends on the standard or lack of standard used... Technically, we actually already do the 2nd option quite a bit. Here's a few examples: POST /api/v1/return_claims POST /api/v1/erm/usage_data_providers/{erm_usage_data_provider_id}/process_COUNTER_file POST /api/v1/holds/{hold_id}/suspension PUT /api/v1/import_batches/{import_batch_id}/records/{import_record_id}/matches/chosen I think we're worried about /api/v1/rpc becoming the wild west, but it seems like we're already in a bit of a wild west scenario with the "REST" API. REST is great for CRUD, but Koha - server side - does a lot more than just CRUD. We're not expecting the REST API consumer to do processing. We're expecting Koha to do the processing, which means we need to support performing actions on the server by API somehow. I don't think there's really a "right or wrong" here. At the moment, I think options 1 and 2 are probably the most practical, as they're already established practices in Koha. -- You are receiving this mail because: You are watching all bug changes.