Bug 22615

Summary: Add routes for /ill_backends
Product: Koha Reporter: Josef Moravec <josef.moravec>
Component: REST APIAssignee: Josef Moravec <josef.moravec>
Status: CLOSED FIXED QA Contact:
Severity: enhancement    
Priority: P5 - low CC: 1joynelson, black23, martin.renvoize
Version: unspecified   
Hardware: All   
OS: All   
URL: https://wiki.koha-community.org/wiki/Illbackends_endpoint_RFC
Change sponsored?: --- Patch complexity: ---
Documentation contact: Documentation submission:
Text to go in the release notes:
Version(s) released in:
20.05.00
Attachments: Bug 22615: Add /ill_backends endpoint
Bug 22615: Add /ill_backends endpoint
Bug 22615: Add endpoint for getting one ill backend
Bug 22615: Fix perlcritic
Bug 22615: Add /ill_backends endpoint
Bug 22615: Add endpoint for getting one ill backend
Bug 22615: Fix perlcritic
Bug 22615: Add /ill_backends endpoint
Bug 22615: Add endpoint for getting one ill backend
Bug 22615: Fix perlcritic

Description Josef Moravec 2019-04-01 15:04:51 UTC

    
Comment 1 Josef Moravec 2019-04-01 15:08:43 UTC
Created attachment 87284 [details] [review]
Bug 22615: Add /ill_backends endpoint
Comment 2 Josef Moravec 2019-04-01 15:10:47 UTC
This is work-in-progress, but I am sharing it in hope I got some feedback.

We need to think of what should be capabilities structure presented in response. For now I used raw data returned by $backend->capabilities method.
Comment 3 Andrew Isherwood 2019-04-02 09:00:18 UTC
Hi Josef

Looking good so far :)

Do you have any details of your intended use case(s) for this endpoint, as that may help inform what the capabilities structure should be.

Is this intended to be functionally distinct from the 'capabilities' embed on the GET /illrequests endpoint?
Comment 4 Josef Moravec 2019-04-03 10:03:20 UTC
(In reply to Andrew Isherwood from comment #3)
> Hi Josef
> 
> Looking good so far :)
> 
> Do you have any details of your intended use case(s) for this endpoint, as
> that may help inform what the capabilities structure should be.
> 
> Is this intended to be functionally distinct from the 'capabilities' embed
> on the GET /illrequests endpoint?

This would be useful for external api clients to know the backends and its capabilities before the request is created - for example unmediated ill through other opacs  like VuFind.

Another use case could be for creating ill systems (at district, national level for example...)

It is not intended to be distinct from /illrequests endpoint, but I think backends another resources, so should have own endpoint ;)
Comment 5 Andrew Isherwood 2019-04-04 09:22:36 UTC
I think the structure currently returned in /illrequests?embed=capabilities (which is just a JSON representation of what is returned from $backend->capabilities) is fairly logical:

{
	"CANCREQ": {
		"id": "CANCREQ",
		"method": 0,
		"name": "Cancellation requested",
		"next_actions": ["KILL", "REQ", "MIG"],
		"prev_actions": ["NEW"],
		"ui_method_icon": 0,
		"ui_method_name": 0
	},
	"COMP": {
		"id": "COMP",
		"method": "mark_completed",
		"name": "Completed",
		"next_actions": [],
		"prev_actions": ["REQ"],
		"ui_method_icon": "fa-check",
		"ui_method_name": "Mark completed"
	},
	"EDITITEM": {
		"id": "EDITITEM",
		"method": "edititem",
		"name": "Edited item metadata",
		"next_actions": [],
		"prev_actions": ["NEW"],
		"ui_method_icon": "fa-edit",
		"ui_method_name": "Edit item metadata"
	},
	"GENREQ": {
		"id": "GENREQ",
		"method": "generic_confirm",
		"name": "Requested from partners",
		"next_actions": ["COMP", "MIG"],
		"prev_actions": ["NEW", "REQREV", "MIG"],
		"ui_method_icon": "fa-send-o",
		"ui_method_name": "Place request with partners"
	},
	"KILL": {
		"id": "KILL",
		"method": "delete",
		"name": 0,
		"next_actions": [],
		"prev_actions": ["QUEUED", "REQREV", "NEW", "CANCREQ", "MIG"],
		"ui_method_icon": "fa-trash",
		"ui_method_name": "Delete request"
	},
	"MIG": {
		"id": "MIG",
		"method": "migrate",
		"name": "Switched provider",
		"next_actions": ["REQ", "GENREQ", "KILL", "MIG"],
		"prev_actions": ["NEW", "REQ", "GENREQ", "REQREV", "QUEUED", "CANCREQ", "MIG"],
		"ui_method_icon": "fa-search",
		"ui_method_name": "Switch provider"
	},
	"NEW": {
		"id": "NEW",
		"method": "create",
		"name": "New request",
		"next_actions": ["REQ", "GENREQ", "KILL", "MIG", "EDITITEM"],
		"prev_actions": [],
		"ui_method_icon": "fa-plus",
		"ui_method_name": "New request"
	},
	"QUEUED": {
		"id": "QUEUED",
		"method": 0,
		"name": "Queued request",
		"next_actions": ["REQ", "KILL", "MIG"],
		"prev_actions": [],
		"ui_method_icon": 0,
		"ui_method_name": 0
	},
	"REQ": {
		"id": "REQ",
		"method": "confirm",
		"name": "Requested",
		"next_actions": ["REQREV", "COMP", "MIG"],
		"prev_actions": ["NEW", "REQREV", "QUEUED", "CANCREQ", "MIG"],
		"ui_method_icon": "fa-check",
		"ui_method_name": "Confirm request"
	},
	"REQREV": {
		"id": "REQREV",
		"method": "cancel",
		"name": "Request reverted",
		"next_actions": ["REQ", "GENREQ", "KILL", "MIG"],
		"prev_actions": ["REQ"],
		"ui_method_icon": "fa-times",
		"ui_method_name": "Revert Request"
	}
}


So maybe a JSON object, keyed on backend name (e.g. BLDSS, FreeForm), with the the object being the above object? So:

{
    "BLDSS": {
        "CANCREQ": {
	    "id": "CANCREQ",
	    "method": 0,
	    "name": "Cancellation requested",
	    "next_actions": ["KILL", "REQ", "MIG"],
	    "prev_actions": ["NEW"],
	    "ui_method_icon": 0,
	    "ui_method_name": 0
	},
        [..etc..]
    },
    "FreeForm": {
        [...etc...]
    }
}

Having an object keyed on name, rather than an array would slightly simplify lookup.

In addition to getting all backends, I'm guessing it would be useful to have a search endpoint, such as /ill_backends?backend=FreeForm , which would just return a single backend.

Hope this is helpful?!
Comment 6 Josef Moravec 2019-04-04 09:31:16 UTC
(In reply to Andrew Isherwood from comment #5)
> I think the structure currently returned in /illrequests?embed=capabilities
> (which is just a JSON representation of what is returned from
> $backend->capabilities) is fairly logical:
> 
> {
> 	"CANCREQ": {
> 		"id": "CANCREQ",
> 		"method": 0,
> 		"name": "Cancellation requested",
> 		"next_actions": ["KILL", "REQ", "MIG"],
> 		"prev_actions": ["NEW"],
> 		"ui_method_icon": 0,
> 		"ui_method_name": 0
> 	},
> 	"COMP": {
> 		"id": "COMP",
> 		"method": "mark_completed",
> 		"name": "Completed",
> 		"next_actions": [],
> 		"prev_actions": ["REQ"],
> 		"ui_method_icon": "fa-check",
> 		"ui_method_name": "Mark completed"
> 	},
> 	"EDITITEM": {
> 		"id": "EDITITEM",
> 		"method": "edititem",
> 		"name": "Edited item metadata",
> 		"next_actions": [],
> 		"prev_actions": ["NEW"],
> 		"ui_method_icon": "fa-edit",
> 		"ui_method_name": "Edit item metadata"
> 	},
> 	"GENREQ": {
> 		"id": "GENREQ",
> 		"method": "generic_confirm",
> 		"name": "Requested from partners",
> 		"next_actions": ["COMP", "MIG"],
> 		"prev_actions": ["NEW", "REQREV", "MIG"],
> 		"ui_method_icon": "fa-send-o",
> 		"ui_method_name": "Place request with partners"
> 	},
> 	"KILL": {
> 		"id": "KILL",
> 		"method": "delete",
> 		"name": 0,
> 		"next_actions": [],
> 		"prev_actions": ["QUEUED", "REQREV", "NEW", "CANCREQ", "MIG"],
> 		"ui_method_icon": "fa-trash",
> 		"ui_method_name": "Delete request"
> 	},
> 	"MIG": {
> 		"id": "MIG",
> 		"method": "migrate",
> 		"name": "Switched provider",
> 		"next_actions": ["REQ", "GENREQ", "KILL", "MIG"],
> 		"prev_actions": ["NEW", "REQ", "GENREQ", "REQREV", "QUEUED", "CANCREQ",
> "MIG"],
> 		"ui_method_icon": "fa-search",
> 		"ui_method_name": "Switch provider"
> 	},
> 	"NEW": {
> 		"id": "NEW",
> 		"method": "create",
> 		"name": "New request",
> 		"next_actions": ["REQ", "GENREQ", "KILL", "MIG", "EDITITEM"],
> 		"prev_actions": [],
> 		"ui_method_icon": "fa-plus",
> 		"ui_method_name": "New request"
> 	},
> 	"QUEUED": {
> 		"id": "QUEUED",
> 		"method": 0,
> 		"name": "Queued request",
> 		"next_actions": ["REQ", "KILL", "MIG"],
> 		"prev_actions": [],
> 		"ui_method_icon": 0,
> 		"ui_method_name": 0
> 	},
> 	"REQ": {
> 		"id": "REQ",
> 		"method": "confirm",
> 		"name": "Requested",
> 		"next_actions": ["REQREV", "COMP", "MIG"],
> 		"prev_actions": ["NEW", "REQREV", "QUEUED", "CANCREQ", "MIG"],
> 		"ui_method_icon": "fa-check",
> 		"ui_method_name": "Confirm request"
> 	},
> 	"REQREV": {
> 		"id": "REQREV",
> 		"method": "cancel",
> 		"name": "Request reverted",
> 		"next_actions": ["REQ", "GENREQ", "KILL", "MIG"],
> 		"prev_actions": ["REQ"],
> 		"ui_method_icon": "fa-times",
> 		"ui_method_name": "Revert Request"
> 	}
> }
> 
> 
> So maybe a JSON object, keyed on backend name (e.g. BLDSS, FreeForm), with
> the the object being the above object? So:
> 
> {
>     "BLDSS": {
>         "CANCREQ": {
> 	    "id": "CANCREQ",
> 	    "method": 0,
> 	    "name": "Cancellation requested",
> 	    "next_actions": ["KILL", "REQ", "MIG"],
> 	    "prev_actions": ["NEW"],
> 	    "ui_method_icon": 0,
> 	    "ui_method_name": 0
> 	},
>         [..etc..]
>     },
>     "FreeForm": {
>         [...etc...]
>     }
> }
> 
> Having an object keyed on name, rather than an array would slightly simplify
> lookup.

I used array, because of consistancy with other endpoints - we always return array on search, otherwise, I think we could stick with raw capabilites, as it is
 
> In addition to getting all backends, I'm guessing it would be useful to have
> a search endpoint, such as /ill_backends?backend=FreeForm , which would just
> return a single backend.

Yes, that could be useful.


> Hope this is helpful?!


It is! ;)
Comment 7 Andrew Isherwood 2019-04-04 09:34:57 UTC
(In reply to Josef Moravec from comment #6)

> I used array, because of consistancy with other endpoints - we always return
> array on search <snip>

Yes, good point!

Do you think this needs more discussion or would you be happy for me to sign it off?
Comment 8 Josef Moravec 2019-04-04 09:42:42 UTC
(In reply to Andrew Isherwood from comment #7)
> (In reply to Josef Moravec from comment #6)
> 
> > I used array, because of consistancy with other endpoints - we always return
> > array on search <snip>
> 
> Yes, good point!
> 
> Do you think this needs more discussion or would you be happy for me to sign
> it off?

I'll add the get one method, polish rfc and you can then sign off i think, I'll bring it to development meeting next week for discussion/voting. 

Thanks for your feedback!
Comment 9 Josef Moravec 2020-01-22 14:24:59 UTC
Created attachment 97735 [details] [review]
Bug 22615: Add /ill_backends endpoint
Comment 10 Josef Moravec 2020-01-22 14:25:03 UTC
Created attachment 97736 [details] [review]
Bug 22615: Add endpoint for getting one ill backend
Comment 11 Josef Moravec 2020-01-22 14:25:07 UTC
Created attachment 97737 [details] [review]
Bug 22615: Fix perlcritic
Comment 12 Josef Moravec 2020-01-22 14:29:57 UTC
The RFC was voted some time ago.

Now I added a single backend endpoint.

Test plan:
1) Apply the patch
2) restart_all
3) Try to get all backends using /ill_backends endpoint
4) Try to get one backend using /ill_backends/{backend_id/name}
for exampler /ill_backends/FreeForm
Comment 13 Andrew Isherwood 2020-01-22 15:14:53 UTC
Created attachment 97742 [details] [review]
Bug 22615: Add /ill_backends endpoint

Signed-off-by: Andrew Isherwood <andrew.isherwood@ptfs-europe.com>
Comment 14 Andrew Isherwood 2020-01-22 15:14:56 UTC
Created attachment 97743 [details] [review]
Bug 22615: Add endpoint for getting one ill backend

Signed-off-by: Andrew Isherwood <andrew.isherwood@ptfs-europe.com>
Comment 15 Andrew Isherwood 2020-01-22 15:14:59 UTC
Created attachment 97744 [details] [review]
Bug 22615: Fix perlcritic

Signed-off-by: Andrew Isherwood <andrew.isherwood@ptfs-europe.com>
Comment 16 Kyle M Hall 2020-03-04 18:50:21 UTC
Created attachment 100148 [details] [review]
Bug 22615: Add /ill_backends endpoint

Signed-off-by: Andrew Isherwood <andrew.isherwood@ptfs-europe.com>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 17 Kyle M Hall 2020-03-04 18:50:52 UTC
Created attachment 100149 [details] [review]
Bug 22615: Add endpoint for getting one ill backend

Signed-off-by: Andrew Isherwood <andrew.isherwood@ptfs-europe.com>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 18 Kyle M Hall 2020-03-04 18:50:55 UTC
Created attachment 100150 [details] [review]
Bug 22615: Fix perlcritic

Signed-off-by: Andrew Isherwood <andrew.isherwood@ptfs-europe.com>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Comment 19 Martin Renvoize 2020-03-05 13:06:14 UTC
Nice work everyone!

Pushed to master for 20.05
Comment 20 Joy Nelson 2020-04-01 22:11:04 UTC
enhancement not backported to 19.11.x