Design Principles

Although the Nexpose gem currently contains a few disparate design approaches, we want to move toward a singular design principle that keeps the interface uniform and easy to understand. This document seeks to lay out those principles.

Types of Objects

Where possible, all data structures in the Nexpose gem should be objects. Among those objects, there are two general types: data access and data manipulation.

In general, when an object is only useful for data access, it should follow the form ...Summary. When an object is meant to be used for data manipulation, such as changing existing configuration or adding new data, then it should have a name that directly reflects the object. For example, SiteSummary versus Site. SiteSummary represents a read-only view of site information, returned by a site listing request for all sites. Site, on the other hand, represent a single site that the user wished to manipulate. The word "Config" should be avoided in class names (with the exception of ReportConfig).

Calls on the Connection

Quite a few calls are made directly against the connection. These include listing, search, and delete requests.

Where possible, these methods should be named "verb_object". For example, delete_engine or list_sites. It is also reasonable to alias these to simple call "sites" for the listing requests.

Passing the Connection

The Connection object should not be saved inside other objects. When a data manipulation object needs to persist changes to a console, the connection should be passed into the call. So saving a site should be site.save(nsc)

Consistent Names

Because the gem crosses different versions of the Nexpose API, each with different call semantics, the gem should attempt to unify that interface. As such, configuration objects should favor the method names load, save, and delete over other alternatives.

Avoid Repetition

The gem should strive to avoid calls that will duplicate semantic names. For example, having site.site_id provides no additional details over site.id, just more typing.

Private Methods

There are a number of methods in the gem which aren't meant for external consumption but which cannot be made private in Ruby and still maintain usability. All methods which aid in the development of the gem but do not provide a clear customer-facing value should be documented as such.