[commits] [Wiki] changed: Project/HordeApiRewrite
rlang Thu, 12 Apr 2018 21:04:43 + 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
[commits] [Wiki] changed: Project/HordeApiRewrite
rlang Sun, 01 Apr 2018 20:56:48 + Modified page: https://wiki.horde.org/Project/HordeApiRewrite New Revision: 3 Change log: Consider some RPCs @@ -167,8 +167,61 @@ App Level: Upstream provides defaults on which RPC methods are available and how they are protected (multiple available). Admin / Config may override, empty config uses defaults + +++ API characteristics + +LOCAL: INTERNAL + +- use registry to discover API methods and their implementations +- any api/method combination may be served by any application (registry knows) +- no real metadata on parameter count and formats available +- currently no named parameters +- can directly use objects as parameters or return types (rarely used yet, breaks external apis as of now) + +RPC: JSON-RPC, XML-RPC + +- use registry to discover API methods and their implementations +- wraps INTERNAL API in specific formats (JSON, XML) +- Currently breaks for INTERNAL apis which use objects +- Requires authentication, but any authorization/limits beyond that is left to the INTERNAL method implementation +- Needs custom serialization for API objects which don't implement __toString +- In theory, named parameters are possible, but the Horde infrastructure can't handle them +- HTTP-wise, it's POST to a well-known endpoint +- need to parse data to find the appropriate api/method, hence implementation + + +Webdav, Caldav, Carddav: +- Fixed set of methods +- Webdav implemented for multiple resources, Caldav/Carddav backends are really designed to work for one app each +- No need to discover or route methods, can use fixed class layout for implementation (browse, delete, ...) + +REST: +- Resource-centric +- Should we assume each registry API is a resource? +- Any URL formats and lengths possible, +- methods per resource should be limited to http verbs +- multiple input and output formats may be governed by content type +- Supports multiple API versions in parallel (either by URL or by content type) +- each request must be authenticated, no sessions. + +Horde AJAX Framework +- Not currently part of the RPC family +- separate endpoint +- URL exposes application and method +- Uses cookies/sessions/tokens +- mostly JSON + + +SOAP: +- Unsure if it really still works +- similar to XML-RPC +- but SHOULD generate meta information for the client (where? how?) + +Common: +- We can discern each http remote protocol by URL and/or content type. What is not covered, should be assumed REST. +- Once we know the protocol, we know how to find out API and method (and, via registry, implementation) ++ Resources -- commits mailing list Frequently Asked Questions: http://wiki.horde.org/FAQ To unsubscribe, mail: commits-unsubscr...@lists.horde.org
[commits] [Wiki] changed: Project/HordeApiRewrite
rlang Sun, 18 Mar 2018 10:44:33 + Modified page: https://wiki.horde.org/Project/HordeApiRewrite New Revision: 2 Change log: Update to reflect discussions on dev@ and current progress. @@ -61,21 +61,37 @@ The registry allows limited runtime introspection (hasMethod, listMethods, listApis) but no hints on input/output formats (parameter list and type) ++ Proposed H6 API changes -* Split $App_Api class into $Api_Api classes - Apis still need to be registered in registry. (MEDIUM) +* 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 -> maybe only needed for external interfaces? (Needed for REST, maybe SOAP) + +* Implement parameter and return hints -- TBD -> only needed for external interfaces? (Needed for REST, maybe SOAP) * 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. + 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: -Check if api exists (for RPC access / individual RPC type) -Check if method exists (for RPC access / individual RPC type) +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 -- commits mailing list Frequently Asked Questions: http://wiki.horde.org/FAQ To unsubscribe, mail: commits-unsubscr...@lists.horde.org
