Latest revision as of 14:37, 30 April 2014

Design

The intention of this document is to give a high level picture of the design of the OpenStack Python SDK. This document should cover how the SDK appears from the user perspective and important details of the internal design that the average user should not need to worry about.

User Interface Design

Internal Design

The internal design section of this document should cover aspects of the SDK that the typical user will not need to know. Developers and advanced users may find this information useful.

Authenticator

The Authenticator class is responsible for providing a valid authentication token and an appropriate endpoint for a service type. The authenticator can use a Transport to get a valid token if needed.

Connection

The internal design of the OpenStack Python SDK is based on the OSI Model where the application is the resource object. The objects are described in more detail below.

Resource

The Resource class represents a resource in the cloud, such as a compute instance, a stored object, a network, etc. Rather than have fixed attributes, its attributes should be populated with the information returned from the API. Every resource should have an id attribute; in the cases where there is not a native id, such as a stored object in Swift, an 'id' property should be created to return the unique identifier for the resource, such as a name. Well known attributes of a resource should be accessible through properties of the class.

Presentation

The job of the presentation layer is encoding and decoding of messages in the desired format. The default format is json and that is the only type currently supported, but it would be easy to add support for xml or text/plain. The Presentation class also manages the 'Accept' and 'Content-Type' headers to indicate the type of encoding. The presentation layer expects to communicate with a session layer.

Session

The session layer is responsible for maintaining an authorized session using the Authenticator. The authenticator is expected to provide a valid authentication token and an endpoint. The session layer manages the 'X-Auth-Token' header and sends requests over a transport layer. The session layer also makes sure the request is routed to the appropriate endpoint.

Transport

The Transport class is a wrapper for the requests.Session class and adds some common OpenStack functionality. The transport manages SSL certificate verification, the 'User-Agent' header and HTTP redirects. The transport also will allow logging of requests.

@@ Line 1: / Line 1: @@
-== Introduction ==
+= Design =
+The intention of this document is to give a high level picture of the design of the OpenStack Python SDK.  This document should cover how the SDK appears from the user perspective and important details of the internal design that the average user should not need to worry about.
-In order to help make this SDK easy to develop, maintain, and test, a clean class design with clearly separated responsibilities is important. This is just one possibility, based on work done on the python-novaclient library. In an attempt to simplify things, the Identity class has been left out, as it is an entire discussion in and of itself. For the purposes of this discussion, assume that Identity is present and can do everything that is needed.
+== User Interface Design ==
-Here is a general overview of the proposed class relationships:
+== Internal Design ==
+The internal design section of this document should cover aspects of the SDK that the typical user will not need to know.  Developers and advanced users may find this information useful.
-[[File:Python sdk class design.png|none|center|Class Design Overview]]
+=== Authenticator ===
+The '''Authenticator''' class is responsible for providing a valid authentication token and an appropriate endpoint for a service type.  The authenticator can use a '''Transport''' to get a valid token if needed.
-''NOTE: For this discussion, the term 'Client' has been used to refer to the class that acts as the interface between the application code and the SDK. This is not a universally-loved term, and changing it to something else will not affect the design itself. Similarly, the class that handles all the HTTP traffic has been named 'HTTP', but that is also not critical.''
+=== Connection ===
+The internal design of the OpenStack Python SDK is based on the [http://en.wikipedia.org/wiki/OSI_model OSI Model] where the application is the resource object.  The objects are described in more detail below.
-== Class Overview ==
+[[File:OpenStack_Python_SDK_Stack.png|none|center|OpenStack Python SDK Stack]]
-==== Client ====
-For each service there is a single '''Client''' class that contains the interface that the application developer will work with. Any functionality in the SDK should be available as a method in the Client class. Each Client instance has a reference to an instance of its Manager class. There is no logic in the Client class except to pass the request to its manager, and return the result from the manager to the application.
-==== Manager ====
-The '''Manager''' class contains the logic to construct the appropriate URIs from the base endpoints (returned from the service catalog), and the particulars of the request. If needed, it also creates the appropriate data to include with the request. It then passes that request to the HTTP class, and handles the response. If there is an exception, the appropriate class of Exception is determined and raised with the information the developer would need to understand and correct the exception. Otherwise, the Manager returns the appropriate response, which can be '''None''', or it can be one or more Resource objects.
 ==== Resource ====
-The '''Resource''' class represents a resource in the cloud, such as a compute instance, a stored object, a network, etc. Rather than have fixed attributes, its attributes should be populated with the information returned from the API. Every resource should have an '''id''' attribute; in the cases where there is not a native id, such as a stored object in Swift, an 'id' property should be created to return the unique identifier for the resource, such as a name.
+The '''Resource''' class represents a resource in the cloud, such as a compute instance, a stored object, a network, etc. Rather than have fixed attributes, its attributes should be populated with the information returned from the API. Every resource should have an '''id''' attribute; in the cases where there is not a native id, such as a stored object in Swift, an 'id' property should be created to return the unique identifier for the resource, such as a name.  Well known attributes of a resource should be accessible through properties of the class.
-==== HTTP ====
-The '''HTTP''' class handled all communication between the local system and the API server. This functionality is separated out in order to make testing simpler, so that it can be replaced with a local API 'server' that acts as a test double.
-<hr />
-While the Client class is the interface to the developer using this SDK in their applications, there is one exception for convenience: Resource objects may be interacted with directly where appropriate. In general any time you have a method that looks like:
-<code>client.some_method(resource)</code>
-you should be able to work directly with the resource:
-<code>resource.some_method()</code>
-For example, if you have a reference <code>server</code> to a compute resource, wish to delete a compute resource, you could call either <code>compute_client.delete(server)</code>, or <code>server.delete()</code>, and they would both result in the same action.
-== Common Methods ==
-The Client class should have methods that correspond to the most common actions across all the service APIs:
-* <code>client.get(id)</code> - Returns the resource corresponding to the specified ID.
-* <code>client.list(pagination_params)</code> - Returns a list of zero or more resources, optionally limited by pagination parameters.
-* <code>client.update(resource_or_id, keyword1=value1, keyword2=value2, ...)</code> - Updates the specified resource with the named values.
-* <code>client.create(list_of_values)</code> - Creates a new resource. The values required will vary between services.
-* <code>client.delete(resource_or_id)</code> - Deletes the specified resource.
+==== Presentation ====
+The job of the presentation layer is encoding and decoding of messages in the desired format.  The default format is json and that is the only type currently supported, but it would be easy to add support for xml or text/plain.  The '''Presentation''' class also manages the 'Accept' and 'Content-Type' headers to indicate the type of encoding.  The presentation layer expects to communicate with a session layer.
-== Flexibility ==
+==== Session ====
+The session layer is responsible for maintaining an authorized session using the '''Authenticator'''.  The authenticator is expected to provide a valid authentication token and an endpoint.  The session layer manages the 'X-Auth-Token' header and sends requests over a transport layer.  The session layer also makes sure the request is routed to the appropriate endpoint.
-Whenever possible, equivalent parameters should be accepted. E.g., when acting on a resource, the user should be able to either supply the ID of that resource, or an instance on the Resource class corresponding to that resource.
+==== Transport ====
+The '''Transport''' class is a wrapper for the requests.Session class and adds some common OpenStack functionality.  The transport manages SSL certificate verification, the 'User-Agent' header and HTTP redirects.  The transport also will allow logging of requests.

Difference between revisions of "PythonOpenStackSDK/ClassDesignDiscussion"