rvbd.common.service
This module defines the Service class and associated authentication classes. The Service class is not instantiated directly, but is instead subclassed to implement handlers for particular REST namespaces.
For example, the Shark is based on Service using the "shark" namespace, and will provide the necesary methods to interace with the REST resources available within that namespace.
If a device or appliance implements multiple namespaces, each namespace will be exposed by a separate child class. The Cascade Express product implements both the "profiler" and "shark" namespaces. These will be exposed via Shark and Profiler classes respectively, both based on the the Service class. A script that interacts with both namespaces must instantiate two separate objects.
Service
class rvbd.common.service.Service
This class is the main interface to interact with a device via REST and provides the following functionality:
- Connection management
- Resource requests and responses
- Authentication
- "common" resources
A connection is established as soon as the an instance of this object
is created. Requests can be made via the Service.conn
property.
Service(service, host=None, port=None, auth=None, force_ssl=None, versions=None)
host
is the name or IP address of the device to connect to
port
is the TCP port to use for the connection. This may be either
a single port or a list of ports. If left unset, the port will
automatically be determined.
auth
defines the authentication method and credentials to use
to access the device. See UserAuth and OAuth. If set to None,
connection is not authenticated.
force_ssl
when set to True will only allow SSL based connections.
If False, only allow non-SSL connections. If set to None
(the default) try SSL first, then try non-SSL.
versions
is the API versions that the caller can use.
if unspecified, this will use the latest version supported
by both this implementation and service requested. This does
not apply to the "common" resource requests.
Authenticate with device using the defined authentication method. This sets up the appropriate authentication headers to access restricted resources.
End the authenticated session with the device.
Ping the service. On failure, this raises an exception
check_api_versions(api_versions)
Check that the server supports the given API versions.
Authentication
Most REST resource calls require authentication. Devices will support one or more authentication methods. The following methods may be supported:
-
Auth.OAUTH
- OAuth 2.0 based authentication using an access code. The access code is used to retrieve an access token which is used in subsequent REST calls. -
Auth.COOKIE
- session based authentication via HTTP Cookies. The initial authentication uses username and password. On success, an HTTP Cookie is set and used for subsequesnt REST calls. -
Auth.BASIC
- simple username/password based HTTP Basic authentication.
When a Service object is created, the user may either pass an authentication
object to the constructor, or later passed to the service.authenticate()
method.
UserAuth
class rvbd.common.service.UserAuth
This class is used for both Basic and Cookie based authentication which rely on username and password.
UserAuth(username, password, method=None)
Define an authentication method using username
and password
.
By default this will be used for both Basic as well as Cookie
based authentication methods (whichever is supported by the target).
Authentication can be restricted by setting the method
to
either Auth.BASIC
or Auth.COOKIE
.
OAuth
class rvbd.common.service.OAuth
This class is used for OAuth based authentication with relies on an OAuth access token.
OAuth(access_code)
Define an OAuth based authentication method using access_code
.
The method is automatically set to Auth.OAUTH
.