![](https://secure.gravatar.com/avatar/173371753ea2206b9934a9be1bdce423.jpg?s=120&d=mm&r=g)
On Jul 13, 2012, at 05:43 PM, Richard Wackerbarth wrote:
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, ... )
Actually, I think it's essential that we describe the service in terms of resources and locations. The pseudo-code above is an example of a language binding, but isn't enough because the implementer of that binding would not know where to point the proxy, or how to do the HTTP calls, etc. In fact, the pseudo-code would look significantly different depending on what implementation language is used (the above looks Pythonic, but what about Ruby, or JavaScript?).
If we're using REST then the description of the service must be in terms of the API that REST exposes, e.g. URLs and JSON (for example). Then authors of the language bindings can expose them to client code in whatever way makes sense.
Take a look at the work done in Postorius for accessing the core's REST API.
There's a mailman.client
package which is essentially this Python language
binding to the REST API. Then the Django code can call the mailman.client, or
it could do straight up HTTP itself, or the JavaScript on AJAX-y dynamic pages
could do their own calls, etc.
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.
No, we really need the resource locations and definitions because consumers of the user manager will not just be Python code. And even if it were, that Python code has to be translated to dozens or scores of HTTP calls, and those cannot all be configuration options. The base-url to the service will be configurable, yes.
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.
I think you're right that the level of compatibility can be auto-configured. The alternative of course is just EAFP (easier to ask forgiveness, i.e. prepare to catch any errors or handle any missing data).
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.
Kind of. Note that IUser doesn't describe the service, so really the use of that zope.interface, or how the calls are proxied or not is purely an implementation detail of the consumer of the service. I wouldn't even expect all consumers to use IUser, or even Python.
Cheers, -Barry