Top-level objects

Every web service has a top-level “root” object.

>>> from lazr.restfulclient.tests.example import CookbookWebServiceClient
>>> service = CookbookWebServiceClient()

The root object provides access to service-wide objects.

>>> sorted(service.lp_entries)
['featured_cookbook']

>>> sorted(service.lp_collections)
['cookbooks', 'dishes', 'recipes']

Top-level entries

You can access a top-level entry through attribute access.

>>> print service.featured_cookbook.name
Mastering the Art of French Cooking

Top-level collections

You can access a top-level collection through attribute access.

>>> len(service.dishes)
3

Specific top-level collections may support key-based lookups. For instance, the recipe collection does lookups by recipe ID. This is custom code written for this specific web service, and it won’t work in general.

>>> print service.recipes[1].dish.name
Roast chicken

Looking up an object in a top-level collection triggers an HTTP request, and if the object does not exist on the server, a KeyError is raised.

>>> import httplib2
>>> httplib2.debuglevel = 1
>>> debug_service = CookbookWebServiceClient()
send: 'GET ...'
...

>>> recipe = debug_service.recipes[4]
send: 'GET /1.0/recipes/4 ...'
...

>>> recipe = debug_service.recipes[1000]
Traceback (most recent call last):
...
KeyError: 1000

If you want to look up an object without triggering an HTTP request, you can use parentheses instead of square brackets.

>>> recipe = debug_service.recipes(4)
>>> nonexistent_recipe = debug_service.recipes(1000)

>>> sorted(recipe.lp_attributes)
['http_etag', 'id', 'instructions', ...]

The HTTP request, and any potential error, happens when you try to access one of the object’s properties.

>>> print recipe.instructions
send: 'GET /1.0/recipes/4 ...'
...
Preheat oven to...

>>> print nonexistent_recipe.instructions
Traceback (most recent call last):
...
NotFound: HTTP Error 404: Not Found
...

This is useful if you plan to invoke a named operation on the object instead of accessing its properties–this can save you an HTTP request and speed up your applicaiton.

Now, let’s imagine that a top-level collection is misconfigured. We know that the top-level collection of recipes contains objects whose resource type is ‘recipe’. But let’s tell lazr.restfulclient that that collection contains objects of type ‘cookbook’.

>>> from lazr.restfulclient.tests.example import RecipeSet
>>> print RecipeSet.collection_of
recipe
>>> RecipeSet.collection_of = 'cookbook'

Looking up an object will give you something that presents the interface of a cookbook.

>>> not_really_a_cookbook = debug_service.recipes(2)
>>> sorted(not_really_a_cookbook.lp_attributes)
['confirmed', 'copyright_date', 'cuisine'...]

But once you try to access one of the object’s properties, and the HTTP request is made…

>>> print not_really_a_cookbook.resource_type_link
send: 'GET /1.0/recipes/2 ...'
...
http://cookbooks.dev/1.0/#recipe

…the server serves a recipe, and so the client-side object takes on the properties of a recipe. You can only fool lazr.restfulclient up to the point where it has real data to look at.

>>> sorted(not_really_a_cookbook.lp_attributes)
['http_etag', 'id', 'instructions', ...]

>>> print not_really_a_cookbook.instructions
Draw, singe, stuff, and truss...

This isn’t just a defense mechanism: it’s a useful feature when a top-level collection contains mixed subclasses of some superclass. For instance, the launchpadlib library defines the ‘people’ collection as containing ‘team’ objects, even though it also contains ‘person’ objects, which expose a subset of a team’s functionality. All objects looked up in that collection start out as team objects, but once an object’s data is fetched, if it turns out to actually be a person, it switches from the “team” interface to the “people” interface. (This bit of hackery is necessary because WADL doesn’t have an inheritance mechanism.)

If you try to access a property based on a resource type the object doesn’t really implement, you’ll get an error.

>>> not_really_a_cookbook = debug_service.recipes(3)
>>> sorted(not_really_a_cookbook.lp_attributes)
['confirmed', 'copyright_date', 'cuisine'...]
>>> not_really_a_cookbook.cuisine
Traceback (most recent call last):
...
AttributeError: http://cookbooks.dev/1.0/recipes/3 object has no attribute 'cuisine'

Cleanup.

>>> httplib2.debuglevel = 0
>>> RecipeSet.collection_of = 'recipe'

Versioning

By passing in a ‘version’ argument to the client constructor, you can access different versions of the web service.

>>> print service.recipes[1].self_link
http://cookbooks.dev/1.0/recipes/1

>>> devel_service = CookbookWebServiceClient(version="devel")
>>> print devel_service.recipes[1].self_link
http://cookbooks.dev/devel/recipes/1

You can also forgo the ‘version’ argument and pass in a service root that incorporates a version string.

>>> devel_service = CookbookWebServiceClient(
...     service_root="http://cookbooks.dev/devel/", version=None)
>>> print devel_service.recipes[1].self_link
http://cookbooks.dev/devel/recipes/1

Error reporting

If there’s an error communicating with the server, lazr.restfulclient raises HTTPError or an appropriate subclass. The error might be a client-side error (maybe you tried to access something that doesn’t exist) or a server-side error (maybe the server crashed due to a bug). The string representation of the error should have enough information to help you figure out what happened.

This example demonstrates NotFound, the HTTPError subclass used when the server sends a 404 error For detailed information about the different HTTPError subclasses, see tests/test_error.py.

>>> from lazr.restfulclient.errors import HTTPError
>>> try:
...    service.load("http://cookbooks.dev/")
... except Exception, e:
...     pass

>>> raise e
Traceback (most recent call last):
...
NotFound: HTTP Error 404: Not Found
Response headers:
---
...
content-type: text/plain
...
---
Response body:
---
...
---

>>> print isinstance(e, HTTPError)
True