API unification

[wmoore]

​http://www.openmicroscopy.org.uk/site/community/minutes/minigroup/api-unification-meetings/2011.03.14

Goal for 4.3 release - stabilise the blitz gateway API

• Reduce method count by using generic methods
• Use this as a model for new OMERO service
• Object wrapper methods should reflect methods of underlying objects

[jburel]

Moved from sprint 2011-02-10 (5)

[wmoore]

Meeting scheduled for Tuesday 15th Feb, 9.30am. Main question to answer is:

• How similar should we attempt to make the Python and Java client APIs?

[wmoore]

Josh's notes from meeting 15th Feb 2011

API unification meeting: Will, Chris, Ola, Jean-Marie, Josh (9:30 UK)

* Initial
   * Will: Still have cleaning up to do
   * Jean-Marie: Need to prevent explosion of gateway methods
       * Start with mgmt methods
       * ...
* Primary question: Do we keep the two synchronized?
   * createGateway
       * Adam used it
       * Will used it in his scripts & examples
   * Chris: have 3 gateways in Python
       * script_utils, GatewayPrx, omero.gateway.BlitzGateway
   * Overview (Will):
       * Certain number of methods in gateway module ("ton of wrappers")
           * Caching (Python-y stuff)
           * Extension point (historical, for Carlos & Ola to work together)
           * Some methods (getComments...) shouldn't necessarily be there
       * Jean-Marie: doesn't scale
       * Will: trying to make it more generic
           * Trying to get rid of "getDataset" etc.
           * getX(id)
           * listY() - convention
           * In Python, you only retrieve the root of the graph
           * Jean-Marie: load methods get whole graph.
       * Chris: @Wrapper around IQuery to prevent pain
           * Good number of the methods are single object retrievals
           * IQuery methods to mirror getObjects identically
           * Will: Wraps with appropriate wrappers.
           * Jean-Marie: purpose is to not have to know which service you are using
           * Jerome etc. want something simplified
           * Josh: are we trying to get away from services?
               * If so, then I'm for a unified API (Java & Python)
           * Chris: endemic of large number of services
               * Band-aiding core issue: to do work need 1/2 objects
               * Purpose would be to get common gateway in place.
       * Will: some of condensed methods have in lower-level service?
           * Jean-Marie: would rather do that.
       * Chris: currently methods expose that findAllByQuery is needed
           * Easy to push down
           * Jean-Marie: have to push them down
       * Will
           * Python would wrap
* Various
   * Chris: pojos hide lack of utility in services
   * Josh/Jean-Marie: could also use this as a method to get rid of pojos (i.e. message passing)
   * Will: can we tell people to start using it
       * Chris: Get rid of script_utils (4.3) in favor of blitz gateway
       * Remove server side gateway for 4.3
       * In the mean time, start moving logic to session or IQuery
       * For 4.3, no large changes to blitz gateway
       * Names are the same as in the model
       * Unifying some of blitz gateway methods
           * Chris: look at all retrieval methods and all getX
           * Figure out what lowest common denominator (e.g. "findExperimenterByName")
           * Need something like findByAttribute
   * Mark a good number as deprecated
       * Start marking methods & services deprecated (gateway, deleted, ...)
       * getObjects and some other are not yet released so can be removed

* Summary:
   * Need to unify these things and clean up our mess
   * Need to do our damndest that this does not continue
       * Everyone CANNOT create methods where they want
       * Is it documentation? Or is it not asking?

* TODOs
   * Wiki page for new remote API: *.slice file (Ice-compatbile objects)
   * Native binding page: omero.client, BlitzGateway/OMEROGateway.java (non-Ice tools)
       * Language- or Framework-specific

[agilo]

Updated status, related task in progress

[wmoore]

Today's meeting Notes - ​https://www.openmicroscopy.org.uk/site/community/minutes/minigroup/api-unification-meetings/2011.02.28

[jmoore]

Moved remaining open tickets to #5926 and closing as part of 4.3.0