Merge lp:~leonardr/lazr.restful/root-resource-url into lp:lazr.restful

[Leonard Richardson]

[Leonard Richardson (leonardr)]

The IWebServiceConfiguration object contains (almost) all information necessary to generate the root URL of a web service. I've written three implementations of the same code to create three different root resource IAbsoluteURL implementations. One for the example web service, one for the example WSGI service, and one for a Canonical internal web service.

This branch moves this basic implementation into lazr.restful.simple, and changes the example web service and example WSGI web service to use the .simple implementation instead of custom implementations.

I added one field to IWebServiceConfiguration: service_root_uri_prefix. This is used in cases when the URI root of the web service is not the top of the hostname. For instance, if the web service is rooted at foo.com/webservice/ instead of webservice.foo.com/.

[lp:~leonardr/lazr.restful/root-resource-url]

69. By Leonard Richardson on 2009-08-20

Added a doctest for RootResourceAbsoluteURL, and added two missing fields to IWebServiceConfiguration.

[Leonard Richardson (leonardr)]

I did another revision that adds a doctest of RootResourceAbsoluteURL and adds 'hostname' and 'port' to IWebServiceConfiguration -- two fields that a lot of code was assuming were present, but which were not defined in the interface.

[lp:~leonardr/lazr.restful/root-resource-url]

70. By Leonard Richardson on 2009-08-20

Replaced line removed by accident.

71. By Leonard Richardson on 2009-08-20

Removed unnecessary imports.

72. By Leonard Richardson on 2009-08-20

Removed abortive attempt at testing service_root_uri_prefix within the example web service.

[Gary Poster (gary)]

(merge-conditional)

Hi Leonard. This is a great branch! The cleanup is very nice, and I can see how it would make the ISD webservice cleaner.

As we discussed on IRC, I'd like the configuration interface to clarify when it is necessary to fill out the new fields. As you said on IRC, for instance, it should not be necessary to fill them out for Launchpad. Maybe in the future we should divide these parts of the configuration interface out.

Other than that, +1.

Thanks,

Gary

review: Approve

=== modified file 'src/lazr/restful/example/configuration.py'
--- src/lazr/restful/example/configuration.py	2009-08-11 18:36:20 +0000
+++ src/lazr/restful/example/configuration.py	2009-08-19 21:06:41 +0000
@@ -19,7 +19,10 @@
     """A configuration object for the cookbook web service."""
     implements(IWebServiceConfiguration)
 
+    hostname = "cookbooks.dev"
+    port = None
     path_override = "api"
+    service_root_uri_prefix = ""
     service_version_uri_prefix = "1.0"
     view_permission = 'lazr.restful.example.View'
     use_https = False

=== modified file 'src/lazr/restful/example/configure.zcml'
--- src/lazr/restful/example/configure.zcml	2009-08-04 18:23:18 +0000
+++ src/lazr/restful/example/configure.zcml	2009-08-19 21:06:41 +0000
@@ -99,12 +99,7 @@
       name="absolute_url"
       />
 
-  <adapter factory="lazr.restful.example.root.CookbookServiceRootAbsoluteURL" />
-
-  <adapter
-      factory="lazr.restful.example.root.CookbookServiceRootAbsoluteURL"
-      name="absolute_url"
-      />
+  <adapter factory="lazr.restful.simple.RootResourceAbsoluteURL" />
 
   <subscriber
    for="lazr.restful.example.interfaces.ICookbook

=== modified file 'src/lazr/restful/example/root.py'
--- src/lazr/restful/example/root.py	2009-05-07 12:31:18 +0000
+++ src/lazr/restful/example/root.py	2009-08-19 21:06:41 +0000
@@ -359,25 +359,3 @@
         """Traverse to a top-level object."""
         obj = self.top_level_names.get(name)
         return obj
-
-
-class CookbookServiceRootAbsoluteURL:
-    """A basic implementation of IAbsoluteURL for the root object."""
-    implements(IAbsoluteURL)
-    adapts(CookbookServiceRootResource, IDefaultBrowserLayer)
-
-    HOSTNAME = "http://cookbooks.dev/"
-
-    def __init__(self, context, request):
-        """Initialize with respect to a context and request."""
-        self.version = getUtility(
-            IWebServiceConfiguration).service_version_uri_prefix
-
-    def __str__(self):
-        """Return the semi-hard-coded base URL for the service."""
-        return self.HOSTNAME + self.version
-
-    def __call__(self):
-        """Return the semi-hard-coded URL to the service root resource."""
-        return str(self) + '/'
-

=== modified file 'src/lazr/restful/example/wsgi/configuration.py'
--- src/lazr/restful/example/wsgi/configuration.py	2009-08-03 13:12:20 +0000
+++ src/lazr/restful/example/wsgi/configuration.py	2009-08-19 19:38:03 +0000
@@ -18,6 +18,7 @@
     path_override = None
     use_https = False
     show_tracebacks = True
+    service_root_uri_prefix = ''
     service_version_uri_prefix = '1.0'
     code_revision = '1'
     default_batch_size = 50

=== modified file 'src/lazr/restful/example/wsgi/configure.zcml'
--- src/lazr/restful/example/wsgi/configure.zcml	2009-08-11 15:26:14 +0000
+++ src/lazr/restful/example/wsgi/configure.zcml	2009-08-19 19:38:03 +0000
@@ -14,8 +14,8 @@
       factory="zope.traversing.browser.absoluteurl.AbsoluteURL"
       />
 
-  <!--This service's root object will generate its own URLs.-->
-  <adapter factory="lazr.restful.example.wsgi.root.WSGIExampleWebServiceRootAbsoluteURL" />
+  <!--This is how the URL to the root resource will be generated.-->
+  <adapter factory="lazr.restful.simple.RootResourceAbsoluteURL" />
 
   <!--Register the service root as the implementation of lazr.restful's IServiceRootResource interface.-->
   <utility

=== modified file 'src/lazr/restful/example/wsgi/root.py'
--- src/lazr/restful/example/wsgi/root.py	2009-08-17 16:22:22 +0000
+++ src/lazr/restful/example/wsgi/root.py	2009-08-19 19:38:03 +0000
@@ -7,15 +7,9 @@
     ]
 
 
-from zope.component import adapts, getUtility
-from zope.interface import implements
-from zope.traversing.browser.interfaces import IAbsoluteURL
-
 from lazr.restful.example.wsgi.resources import (
     IKeyValuePair, PairSet, KeyValuePair)
-from lazr.restful.interfaces import IWebServiceConfiguration
 from lazr.restful.simple import RootResource
-from lazr.restful.publisher import WebServiceRequestTraversal
 
 
 class WSGIExampleWebServiceRootResource(RootResource):
@@ -30,28 +24,3 @@
         collections = dict(pairs=(IKeyValuePair, pairset))
         return collections, {}
 
-
-class WSGIExampleWebServiceRootAbsoluteURL:
-    """A basic implementation of `IAbsoluteURL` for the root object."""
-
-    implements(IAbsoluteURL)
-    adapts(WSGIExampleWebServiceRootResource, WebServiceRequestTraversal)
-
-    def __init__(self, context, request):
-        """Initialize with respect to a context and request."""
-        config = getUtility(IWebServiceConfiguration)
-        self.version = config.service_version_uri_prefix
-        if config.use_https:
-            self.schema = 'https'
-        else:
-            self.schema = 'http'
-        self.hostname = config.hostname
-        self.port = config.port
-
-    def __str__(self):
-        """Return the semi-hard-coded URL to the service root."""
-        if self.port is not None:
-            return "%s://%s:%s/%s" % (self.schema, self.hostname, self.port,
-                                      self.version)
-        return "%s://%s/%s" % (self.schema, self.hostname, self.version)
-    __call__ = __str__

=== modified file 'src/lazr/restful/interfaces/_rest.py'
--- src/lazr/restful/interfaces/_rest.py	2009-07-07 19:42:37 +0000
+++ src/lazr/restful/interfaces/_rest.py	2009-08-19 19:38:03 +0000
@@ -397,10 +397,22 @@
         description=u"Whether or not requests to the web service are secured "
         "through SSL.")
 
+    service_root_uri_prefix = TextLine(
+        title=u"Any URL prefix necessary for the service root.",
+        default=u"",
+        description=u"If your web service is not located at the root of "
+        "its domain (for instance, it's rooted at "
+        "http://foo.com/web-service/ instead of http://api.foo/com/, "
+        "put the URL prefix here. (In the example case, the URL prefix "
+        "is 'web-service/').")
+
     service_version_uri_prefix = Attribute(
         """The versioning string, if any, to use as the URI prefix for web
         service URIs. A popular string is 'beta', but you could also use
-        a version number or the date the API was finalized.""")
+        a version number or the date the API was finalized.
+
+        The service version URI prefix shows up in URIs *after* any
+        value for service_root_uri_prefix.""")
 
     code_revision = Attribute(
         """A string designating the current revision number of the code

=== modified file 'src/lazr/restful/simple.py'
--- src/lazr/restful/simple.py	2009-08-18 19:08:30 +0000
+++ src/lazr/restful/simple.py	2009-08-19 21:06:41 +0000
@@ -14,7 +14,8 @@
 import traceback
 import urllib
 
-from zope.component import adapts, getMultiAdapter, queryMultiAdapter
+from zope.component import (
+    adapts, getMultiAdapter, getUtility, queryMultiAdapter)
 from zope.interface import Attribute, Interface, implements
 from zope.publisher.browser import BrowserRequest
 from zope.publisher.interfaces import IPublication, IPublishTraverse, NotFound
@@ -24,10 +25,12 @@
 from zope.traversing.browser.absoluteurl import _insufficientContext, _safe
 
 from lazr.restful import EntryAdapterUtility, ServiceRootResource
-from lazr.restful.interfaces import ITraverseWithGet, IWebServiceLayer
+from lazr.restful.interfaces import (
+    ITraverseWithGet, IWebServiceConfiguration, IWebServiceLayer)
 from lazr.restful.publisher import (
     WebServicePublicationMixin, WebServiceRequestTraversal)
 
+
 class PublicationMixin(object):
     """A very simple implementation of `IPublication`.
 
@@ -230,6 +233,50 @@
         return ({}, {})
 
 
+class RootResourceAbsoluteURL:
+    """A basic implementation of `IAbsoluteURL` for a root resource."""
+
+    implements(IAbsoluteURL)
+    adapts(ServiceRootResource, WebServiceRequestTraversal)
+
+    def __init__(self, context, request):
+        """Initialize with respect to a context and request."""
+        config = getUtility(IWebServiceConfiguration)
+        self.version = config.service_version_uri_prefix
+        if config.use_https:
+            self.schema = 'https'
+        else:
+            self.schema = 'http'
+        self.hostname = config.hostname
+        self.port = config.port
+        self.prefix = config.service_root_uri_prefix
+
+    def __str__(self):
+        """Return the part of the URL that contains the hostname.
+
+        This is called when constructing the URL for some resource.
+        This string should not end with a slash; Zope's AbsoluteURL
+        will provide the slash when joining this string with the
+        __name__ of the subordinate resource.
+        """
+        if self.port is not None:
+            return "%s://%s:%s/%s%s" % (
+                self.schema, self.hostname, self.port, self.prefix,
+                self.version)
+        return "%s://%s/%s%s" % (
+            self.schema, self.hostname, self.prefix, self.version)
+
+    def __call__(self):
+        """Return the URL to the service root resource.
+
+        This value is called when finding the URL to the service root
+        resource, and it needs to end with a slash so that clients
+        will be able to do relative URL resolution correctly with
+        respect to the service root.
+        """
+        return str(self) + '/'
+
+
 class IMultiplePathPartLocation(Interface):
 
     """An ILocation-like interface for objects with multiple path parts.
@@ -284,4 +331,3 @@
         escaped_parts = [urllib.quote(part.encode('utf-8'), _safe)
                          for part in parts]
         return start_url + "/" + "/".join(escaped_parts)
-    __call__ = __str__