[dev] API Interface Rewrite

[Michael M Slusarz]

Quoting Chuck Hagenbuch <chuck at horde.org>:

>> Take perms().  That is an example of a function that should be the  
>> same across all applications.  However, calling code shouldn't have  
>> to call that method any different from an application specific  
>> method (they should both be callable via call() or  
>> callByPackage()).  Which makes sense because these calls are no  
>> different than an application's API calls.
>
> But they are different - you could make an argument that the only  
> place a list of permissions should be exposed through the API is at  
> the Horde level, where you could request the full tree. Same thing  
> for prefs callbacks - there could be a system API to get at them,  
> but they don't belong at all in a regular application's API. And  
> because of that I don't agree that they should be callable the same  
> way.

OK - I will agree with you here.

>> So that means that these functions now have to parse yet another  
>> file to determine where the function call lies (more overhead).   
>> And we have to create this 'Applicaion_Base' file, which is going  
>> to look identical to the API file since it needs $services and  
>> $types declarations (more overhead, both processing and in code  
>> maintenance).
>
> It shouldn't be necessary to guess where the function call is. There  
> should be two distinct kinds.
>
> Also, one or two PHP class files should not involve performance  
> overhead; if it matters to a specific install they should be using a  
> PHP opcode cache, which should make the overhead negligible on one  
> or two files.

It's not just PHP processing overhead I was worried about - it is the  
maintenance overhead of having to maintain another script.  But that  
will be minimized with this...

> Also, the $services and $types arrays should go away in favor of  
> well-documented and marked up PHP classes.

Since I was never really sure what these were for, this makes complete  
sense.  So API caching at logon will consist of loading an API file  
(if there is one), scanning for the list of public functions, and  
storing that data.  API documentation will be created solely from  
phpdoc comments.  This is a worthy goal in and of itself.

>> I think a well-commented API file is much preferable then trying to  
>> break this out into 2 separate libraries.
>
> I still disagree, so I'm interested in whether this changes your mind or not.

You've convinced me.  It sounds like you have some other plans for  
this interface (should the base class be called Horde_Application_Api?  
Horde_Application? Horde_Application_Base? Horde_Registry_App?), but  
for now would a useful start be to move those Horde-centric API calls  
to the new class?  It also sounds like you would want to call them via  
something like Horde_Registry::callAppMethod() (better name  
suggestions would be great)?

michael

-- 
___________________________________
Michael Slusarz [slusarz at horde.org]