Service
=======

The ``Service`` module contains classes which provide for interacting with the cloud service.

To work with the service, one first needs to create a service object. A service object
takes several required parameters which include:

1) the domain name of the server
2) the account to use to connect to the service
3) the credentials for the account (in this case a password)
4) an API key for the application (issued to you by the service provider)
5) an optional user agent string for your application

Example::

    service = Service("api.example.com", "user@example.com", "my_password", APIKEY, "MyCoolApp/1.0")

Once you have created a service object, you may use that to communicate with the service. Basic methods for actions are provided for ``GET``, ``PUT``, ``POST``, ``LOCK``, and ``UNLOCK`` requests. Convenience methods for working with Resource objects are also provided.

Using the convenience methods require the creation of a Resource and then using that resource as a parameter to the method. Additional documentation on Resources is provided in the Resources module.

Example::

    cloud = Cloud(service.get_serveruri())
    try:
        cloud = service.get_resource(cloud)
    except RestException, ex:
        print ("Failed to retrieve resource: %s" % repr(ex))

.. note::
	The ``Service`` module can be used in two different ways: Resources may be referenced via URI or as ``Resource`` objects. Which way to use is completely dependent on your application.

Referencing Resources via URI
-----------------------------

The following methods all work agains URIs for resources:

.. automethod:: mrcsp.Service.Service.get
.. automethod:: mrcsp.Service.Service.post
.. automethod:: mrcsp.Service.Service.put
.. automethod:: mrcsp.Service.Service.delete
.. automethod:: mrcsp.Service.Service.lock
.. automethod:: mrcsp.Service.Service.unlock

Referencing Resources via ``Resource`` Objects
----------------------------------------------

The following methods require a resource object:

.. automethod:: mrcsp.Service.Service.get_resource
.. automethod:: mrcsp.Service.Service.post_to_resource
.. automethod:: mrcsp.Service.Service.put_resource
.. automethod:: mrcsp.Service.Service.delete_resource

Utilities
---------

.. automethod:: mrcsp.Service.Service.get_serveruri

Logging
-------

Facilities are provided for logging information directly from the ``Service`` module. The intent is mainly for debugging purposes.

.. automethod:: mrcsp.Service.Service.log_response