Skip to content

2. Overall Design

Roshan Joyce edited this page Mar 20, 2015 · 1 revision

In this section we will take a look at the overall design of the SpaceEZ library. The main design goals are as follows:

  1. Encapsulate Junos Space API into a Python class named Space. It should be possible to access all Junos Space web services, collections, and resources hierarchically as members of this class.
  2. Maintain a logical mapping between the way Junos Space API is structured and the containment hierarchy of the Python objects provided by this library. This allows end users to refer to Junos Space API documentation to understand the API and easily map to objects in this library.
  3. Map resources and collections in Junos Space API to Python objects and operate on them in a natural way.
  4. Map HTTP methods (GET, PUT, POST, DELETE) to methods on the Python objects representing resources and collections.
  5. Avoid writing of XML/JSON parsing and formatting code as much as possible for the users of this library.
  6. Organize code in such a way that most of the heavy lifting is done in a few core classes, allowing contributors to easily add/enhance support for web services, collections, and resources by supplying descriptions as YAML files.

High level architecture of the SpaceEZ library is shown below. As you can see, it is built on top of the Requests library. Requests is an elegant and simple HTTP library for Python and SpaceEZ uses it for sending HTTP requests to Junos Space and receiving HTTP responses.

Screen Shot 2014-08-26 at 3.40.28 pm.png

SpaceEZ library is packaged under the namespace jnpr.space.

All HTTP interactions with Junos Space are managed by the Space class in the jnpr.space.rest module. You need to create an instance of this class for each Junos Space cluster that your program needs to access. The Space object that you create will allow you to access all API elements provided by Junos Space platform and the applications hosted on it. These elements are represented by instances of various other classes in the SpaceEZ library. The UML diagram below depicts the main classes and the containment relationships between them.

Screen Shot 2014-08-26 at 4.49.02 pm.png

Applications that are hosted on Junos Space platform are represented by instances of the Application class in the jnpr.space.application module. A Space object contains one Application object for each hosted application and allows you to access the object using the name of the application. For example, Service Now application API has the URL /api/juniper/servicenow. If my_space is a Space object, you can access the contained Service Now application as:

my_space.servicenow

Each web-service exposed by Junos Space platform or a hosted application is represented by an instance of the Service class in the jnpr.space.service module. They are contained either by the Space object (if it is a platform service) or by an Application object (if it is a service provided by a hosted application). Each Service object can be accessed as an attribute of the parent object using its name. For example,

  • my_space.device_management to access the Device Management web-service provided by Junos Space platform.
  • my_space.servicenow.device_management to access the Device Management web-service provided by Service Now application.

A web-service in Junos Space API structure, typically contains one or more collections. Each collection is represented by a Collection object (defined in the jnpr.space.collection module) and is contained by a parent Service object. They can be accessed as attributes of the parent Service object using their names. For example,

  • my_space.device_management.devices to access the devices collection exposed by the Device Management web-service provided by Junos Space platform.
  • my_space.user_management.users to access the users collection exposed by the User Management web-service provided by Junos Space platform.

Collection objects provide a get() method using which the list of contained resources can be retrieved from Junos Space. A get() method invocation on a Collection object automatically translates to an HTTP GET invocation on Junos Space with the appropriate URL and the response is parsed to create a list of resources that is returned to the caller.

Each collection contains resources of the same type. These resources are represented using instances of the Resource class (defined in the jnpr.space.resource module). Resource objects are typically accessed via lists returned by the get() method of Collection objects. For example,

  • my_space.device_management.devices.get() returns a list of Resource objects, each representing a device managed by the Junos Space platform.
  • my_space.user_management.users.get() returns a list of Resource objects, each representing a user account created on the Junos Space platform.

A resource may expose one or more first-class methods that can be invoked on it. These methods are represented using instances of the Method class (defined in the jnpr.space.method module). For example, resources representing a user account on Junos Space provide a method called change-password. There will be a Method object corresponding to this and it can be accessed using the name change_password. Assuming that user1 is a variable referring to a Resource representing a user account, then user1.change_password refers to the change-password method of the resource. And this method can be invoked by calling the post() method on it. That is, user1.change_password.post(...) will invoke this method on Junos Space by sending a POST request with the appropriate URL.

A Service may also contain first-class methods. For example, my_space.device_management.discover_devices to access the discover-devices method on the Device Management web service.

Clone this wiki locally