[Mailman-Developers] Login / User Identification Issues in MM3

[Richard Wackerbarth]

On Jul 13, 2012, at 2:02 PM, Barry Warsaw wrote:

> On Jul 13, 2012, at 11:56 AM, Richard Wackerbarth wrote:
> 
>> Now, hopefully, we can agree that it is necessary to have a "user
>> service". Further it is reasonable to attempt to have this service distinct
>> from the "post routing service".  The question is then "How will these
>> services interface to each other?"
> 
> I think we're definitely converging on a common language for all the moving
> parts.

That, in itself, is significant. 

>> I agree with the "single interface" aspect of it, particularly if that
>> interface is viewed at the functional level rather than at an implementation
>> level. However, I feel that there should be a complete REST binding for that
>> functional interface.
> 
> WADL is, afaik, the definition language for RESTful web services:

From your description, I, also, question what we would gain by attempting to use WADL as our formalization language.

> I would be happy enough with human readable <wink> documentation that
> described this user service in terms of resource locations and contents.

I wouldn't even go that far. The service does not need to be DESCRIBED in terms of locations at all.

Certainly, somewhere in the implementation, we would have to provide that CONFIGURATION information, but from the perspective of a consumer of the "user service", my interface is akin to (expressed as meta-language, not code)

services.user_service.change_password(user_identifier, new_password, ... )

It does not matter where, or how, the user_service processes that information except to the extent that I, and the another services, expect it to persist and can later enquire

password_is_valid = services.user_service.verify_password(user_identifier, submitted_password, ... )

> Although it's been years since I read it, Leonard Richardson's definitive
> O'Reilly book RESTful Web Services talks about how this description can even
> (or maybe *should*) be HTML, with links to the actual resources being
> described.

This is a useful technique for publishing documentation where the service is being exposed to "outside" consumers.
For example, I may learn that there is a RESTful stock quotation service at http:// .....  I know nothing more about it.
Since I will be using http to access the service, it is convenient to publish usage documentation along with data.

However, in a controlled environment, documenting the interface "python style" will, IMHO will be just as useful.

> Or thought about it a different way, mm3's REST API only supports JSON
> representation for resources.  You could implement a parallel representation
> using HTML that included these descriptions.  I bet you could even do this in
> Sphinx in a very human-friendly format, with "base-url" templating so that the
> resource locations are resolvable wherever the user service is deployed.

I'm not opposed to having the documentation published in this, or any other, manner.
I would only hope that doing so can be done following the DRY principle.

> Note that this service can have varying levels of compatibility.  E.g. we
> could say that level 1 is required, and define this as the minimal service
> required by the core.  Things like Facebook id would not be in level 1.
> Higher levels would provide additional information that could be used to
> enhance the user experience.  I have no idea whether more than two levels is
> necessary, but I do think there needs to be some discussion of extensibility.

I have some ideas about ways by which we might even make the interface "auto-configurable".
-- like passing a query of requirements (or reading a list of capabilities)
For example, through the services manager, "ask" it a webUI service is available. If it is, ask the webUI service for the URLs that go into a welcome message.  (Or the alternative, always treat things as if there is a webUI. If the installer has not configured one, then a default stub would return null strings for those requests.

>> This interface can then be implemented by a zope.interface, and/or in any
>> other format appropriate for the implementing code. However, the
>> implementation interface must not provide any inter-service capability that
>> is not reflected in the "interface". Intra-service capabilities are quite
>> useful, particularly when they provide alternate functional signatures which
>> accept local proxies for interacting objects.
>> 
>> Further, as an inter-service design constraint, it should be assumed that the
>> implementation of any service might be "remote" and accessible only by way of
>> the REST interface to it. In addition it should be assumed that the
>> implementation of that service will be in an arbitrary programming language
>> other than python. Designs which violate either of these assumptions should
>> not be accepted because they reduce the ductility of the interface.
>> 
>> The implementation interfaces provide only a proxy for the conceptual objects
>> defined in the service interface and any action on those proxies needs to be
>> conveyed to the conceptual object by means of an access specified in the
>> system interface.
> 
> I think the use of the term "proxy" is informative here.

> Let's say the core only cares about level 1 user service compliance.  Maybe
> that's implemented as an external (to the core) service.  In this case, the
> implementation of interfaces like IUser and IUserManager would simply be
> proxies to this service.  The service itself doesn't care about these
> zope.interfaces, it only cares about providing a level 1 compatible user
> service via REST (probably with a JSON representation).

Yes, but it goes farther than that. Even if the user service is local, in the (core), IUser is still a proxy for the user service. However, for those calls, rather than serializing the data, converting internal object identifiers to external ones, etc. the information is just copied into the corresponding internal structure that the user service builds as it translates a request for REST services.