ILS driver interface cleanup

Details

Description

The current ILS driver interface has evolved during the years to something a bit inconsistent. At least the following aspects could be considered for improving the interface and making it more consistent:

1.) camelCase versus under_scores. Both are used often even in the same context. There are also inconsistencies in camelCasing (dueTime vs. duedate).

2.) It would be nice if 'id' in a returned array would mean the id of the returned entity. It's now usually bib id.

3.) It would be useful to include the full response if it contains more than is normally mapped by default. This would allow one to easily extend what's displayed at least when using a single ILS. There can also be ILS driver configuration-based functionality that needs the data (we have e.g. address change request and need the original values to prefill the form).

4.) Always include the source id especially when using MultiBackend and make it more explicit.

5.) Make input parameters always arrays?

6.) Make results always arrays? E.g. patronLogin now returns null for an unsuccessful login while some other functions return an array with ['success' => false].

7.) Make it possible to return fields as '' instead of having to leave them undefined for them not to be displayed.

Activity

I wonder if it's worth starting this project by introducing versioning and a translation layer... i.e. define what API version 2.0 looks like, and add a getApiVersion() method to the ILS drivers. If the method is missing, assume it's 1.0 (if we want to call what we currently have 1.0) and map the calls accordingly.

This may or may not be a good idea -- but my thought process is that if we change everything at the driver level, we have to rewrite a lot of code that we can't easily test, and it may or may not work right. If we create a translation layer first that adapts the existing code to a new external interface, then we can be more confident that the old code will continue to work, and we can bring all of the consuming code up to date with the new standard. (This translation layer could, for example, be a class that takes any driver object in its constructor and then wraps all of the changed methods, with a generic __call passthrough for all non-changed methods). Then we can upgrade on a driver-by-driver basis to eliminate the need for the translation layer. After a certain amount of time, if nobody is willing to update particular drivers, it's a sign that they may be candidates for deprecation or removal.

Demian Katz
added a comment - 10/Apr/18 10:03 AM I wonder if it's worth starting this project by introducing versioning and a translation layer... i.e. define what API version 2.0 looks like, and add a getApiVersion() method to the ILS drivers. If the method is missing, assume it's 1.0 (if we want to call what we currently have 1.0) and map the calls accordingly.
This may or may not be a good idea -- but my thought process is that if we change everything at the driver level, we have to rewrite a lot of code that we can't easily test, and it may or may not work right. If we create a translation layer first that adapts the existing code to a new external interface, then we can be more confident that the old code will continue to work, and we can bring all of the consuming code up to date with the new standard. (This translation layer could, for example, be a class that takes any driver object in its constructor and then wraps all of the changed methods, with a generic __call passthrough for all non-changed methods). Then we can upgrade on a driver-by-driver basis to eliminate the need for the translation layer. After a certain amount of time, if nobody is willing to update particular drivers, it's a sign that they may be candidates for deprecation or removal.

- Cleanup of the holdings/status interfaces and how they work. At least in some cases it would be useful to be able to define a hierarchy for the holdings, but at least the different request-related fields should be unified and simplified.
- Whether it would be feasible to get rid of different holds_mode and title_level_holds_mode settings in config.ini and move them to the driver level.

Ere Maijala
added a comment - 25/Apr/18 4:40 AM Also worth considering:
- Cleanup of the holdings/status interfaces and how they work. At least in some cases it would be useful to be able to define a hierarchy for the holdings, but at least the different request-related fields should be unified and simplified.
- Whether it would be feasible to get rid of different holds_mode and title_level_holds_mode settings in config.ini and move them to the driver level.

- For fields representing dates, introduce a standard date format; right now there are free-form strings that make upstream programmatic use problematic. It may make sense for backward compatibility to support both structured and string dates, at least for a time.

Demian Katz
added a comment - 17/Dec/18 12:15 PM Another item to consider:
- For fields representing dates, introduce a standard date format; right now there are free-form strings that make upstream programmatic use problematic. It may make sense for backward compatibility to support both structured and string dates, at least for a time.