[commits] [Wiki] changed: Project/HordeApiRewrite

[Ralf Lang (B1 Systems GmbH)]

rlang  Thu, 12 Apr 2018 21:04:43 +0000

Modified page: https://wiki.horde.org/Project/HordeApiRewrite
New Revision:  4
Change log:  We don't need override options. Local integrators can  
simply overload or add classes and change registry to point to it

@@ -60,63 +60,46 @@

  The registry allows limited runtime introspection (hasMethod,  
listMethods, listApis) but no hints on input/output formats (parameter  
list and type)

  ++ Proposed H6 API changes
+
++++ implementation strategy
+
+A runner checks all known ApiTypes (Jsonrpc, Rest, Xmlrpc, ...) if it  
can handle the request until it finds a suitable candidate
+- Each ApiType decides by request headers, URI scheme, request  
method, and request body content to rule out api types as fast/cheap  
as possible
+- A formally suitable apitype checks its router for known command  
implementations which match any parameter set (path, method,  
subdomain...)
+- ApiType unpacks request parameters from apitype specific format
+- Perform any prefilter tasks like authentication, permission  
checking, if required by router configuration.
+- Delegate execution to the implementation class and method found  
from the router
+- pack return value into backend specific format (if not directly  
returned by implementation class)
+- Apply post filters if configured (API accounting, gzip postprocessing,
+- The runner writes the response to the stdout
+OPTIONAL
+- A simplified ApiType for internal/interapp calls allows to skip  
most detection magic but use the extra features is desired - no runner  
needed here
+
+
++++ misc ideas
+

  * Split $App_Api class into $App_Api_$Api classes - Apis still need  
to be registered in registry. (MEDIUM)
  -> Limited support with fallback to $App_Api exists in  
https://github.com/ralflang/Core/tree/class-per-api
  -> needs cleanup
-

  * Implement parameter and return hints -- TBD -> only needed for  
external interfaces? (Needed for REST, maybe SOAP)
+-> Generate openapi data from these hints

  * move DAV browsing/CRUD code to API methods -> Does this also make  
sense for ActiveSync? (OPTIONAL)
-
+
  * Factor method routing out of Horde_Rpc_* into a loadable module to  
decouple Horde_Rpc from the Horde ecosystem (HIGH)
-
+
  -> The Rest feature will not use the Horde_Rpc package, at least in  
its current form. Lessons Learned and helper infrastructure should go  
into a rewrite for Horde_Rpc backends with some smooth transition path.

  -> For any meaningful Rest support, Horde_Controller needs to  
support raw request body.
+https://github.com/horde/Controller/pull/1

  A simple boilerplate router should be part of Horde_Rpc to  
facilitate unit testing
+A Horde-specific router Horde_Core_Rpc_Router should be part of  
Horde_Core and interact with registry

-A Horde-specific router Horde_Core_Rpc_Router should be part of  
Horde_Core and interact with registry:
-Check if api/method exists (for RPC access / individual RPC type) and  
which application is set to provide it
-Check if the method is available in the current RPC api
-
-For Rest:
-Use the first part of the URL to match an to a resource type and find  
its providing app and api version
-Get all possible http request dimensions (method, body, headers,  
parameters, rest of URL...)
-Pass to the application's Rest implementation (class per published resource)
-Let Rest implementation decide what to do
--> try to wrap/serialize to json an interapp api call instead of  
inplace implementation of actual business code here
-
-
-List available apis (for RPC access / individual RPC type) - should be cached
-List available methods (for RPC access / individual RPC type) -  
should be cached
-Find right app to call a specific method
-Find the right runner and configuration for a set of rpc type, api, method
-
-Most RPC types have a fixed request pattern allowing to easily find  
out the API and method to look for - we can easily delegate this to  
the registry/internal API and then check if the found result is  
exposed by the app
-
-Check for class $App_Api_$Api_$Type if it's explicitly allowed for  
this RPC type
-Check for class $App_Api_$Api_Rpc (inherits from Horde_Core_Api_Rpc)  
if it's generally allowed for most RPC types
-
-In Question:
-First check for custom overrides $App_Api_$Api_$TypeLocal and  
$App_Api_$Api_RpcLocal ? Does this hit performance badly?
-
-Don't expose this internal API via RPC at all if no such class exists
-
-REST does not have a fixed request pattern. The Router needs to know  
all REST patterns of all APPs before it can even guess if some  
requested api method exists anywhere. Therefore, REST needs an own  
Horde_Core_Rpc_Router_Rest and the RPC Endpoint rpc.php needs to be  
aware of that fact
-
-For each Api/Provider combination in registry
-Check for class $App_Api_$Api_Rest
-Don't expose this internal API via Rest at all if no such class exists
-
-Each identified Rest request must be checked against this list of  
known REST patterns by Horde_Routes_Mapper.
-Each identified Rest request must have a defined answer format to  
apply to the internal api result (let's check if there is a reasonable  
per-verb default for most cases when implementing)
-
-Horde_Core_Api_Rpc (and descendants)
  Call internal api $App_Api_$Api to actually run a command
  should check what returns for PHP objects and reduce them to arrays  
(__sleep or Serializable)
  allow plugging separate authentication, accounting ...
  may have to be amended by specific classes or config to support some  
RPC types (REST)