*****************
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

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 an HTTPError. 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.

    >>> service.load("http://cookbooks.dev/")
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 404: Not Found
    Response headers:
    ---
    ...
    content-type: text/plain
    ...
    ---
    Response body:
    ---
    ...
    ---
