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:

Service.get(uri, content=None, depth=0, headers={})

Perform an HTTP get operation to the service.

Keyword arguments:

• uri: The URI of the resource to GET
• content: The acceptable content type
• depth: The X-CLOUD-DEPTH to specify
• headers: Additional headers

Exceptions:

• RestException

Service.post(uri, data, content=None, headers={})

Perform a POST operation.

Keyword arguments:

• uri: the URI to post to
• data: the data to post
• content: the content type of the data
• headers: additional headers

Exceptions:

• RestException

Service.put(uri, data, content=None, headers={})

Issue a PUT to a URI.

Keyword arguments:

• uri: The URI to issue the PUT to
• data: The data to PUT to the URI
• content: The content type of the data
• headers: Additional headers

Exceptions:

• RestException

Service.delete(uri, content=None, headers={})

Issue a DELETE.

Keyword arguments:

• uri: The URI to send the DELETE to
• content: The content type to specify
• headers: Additional headers

Exceptions:

• RestException

Service.lock(uri, content=None, headers={})

Issue a LOCK action.

Keyword arguments:

• uri: The URI to issue the LOCK action to
• content: The content type for the request
• headers: Additional headers

Exceptions:

• RestException

Service.unlock(uri, content=None, headers={})

Issue UNLOCK action.

Keyword arguments:

• uri: URI to issue the UNLOCK to
• content: The content type for the request
• headers: Additional headers

Exceptions:

• RestException

Referencing Resources via Resource Objects

The following methods require a resource object:

Service.get_resource(resource, depth=0)

Retrieve a resource from the service, returns a Resource object.

Keyword arguments:

• resource: the Resource object to retrieve
• depth: the X-CLOUD-DEPTH value to use when making the request

Exceptions:

• RestException
• UnsupportedRepresentationException

Service.post_to_resource(target, source)

Post a representation of a resource (source) to another resource (target).

The result of the post is returned.

Keyword arguments:

• target: the Resource to post to
• source: the Resource to be posted

Exceptions:

• RestException

Service.put_resource(resource)

PUT a resource.

Keyword arguments:

• resource: the Resource to PUT

Exceptions:

• RestException

Service.delete_resource(resource)

Delete a Resource.

Keyword arguments:

• resource: The Resource to delete

Exceptions:

• RestException

Utilities

Service.get_serveruri()

Returns the server URI for the service.

The server URI is the single documented resource provided by the API. This URI references the Cloud Resource for the service.

Logging

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

Service.log_response(response)

Utility to log a response.

Keyword arguments:

• response: Response to log