Information Model

REST Resources and Managed Objects

The term "resource" is used in a general sense for any Intersight addressable document specified in the Intersight Management Information Model and identified by a URI. In the Intersight API each addressable REST resource is also called a "Managed Object".

Examples of Intersight Managed Objects include:

• UCS servers
• Server components such as DIMMs, CPUs, GPUs, storage controllers and Cisco CIMC
• UCS Fabric Interconnects
• Firmware inventory
• Hyperflex nodes and Hyperflex cluster
• VLANs and VSANs
• Server, network and storage policies
• Alarms, recommendations and statistics
• Users, roles, and privileges
• Structured and free-text search results
• Collections of other resources.

Intersight Managed Objects are represented using a class hierarchy specified in the OpenAPI specification and available in the downloadable SDKs. All resources are descendants of the mo.Mo abstract class. The table below shows the properties that are common to all Managed Objects.

Table 1: mo.Mo Properties available in all REST resources

Managed Object Identifier (Moid)

Every Managed Object has a unique Moid identifier assigned when the resource is created, such as when an API client sends a HTTP POST request to the Intersight Web service. The Moid embodies the information required to distinguish an Intersight resource from all other resources within its scope of identification.

The Moid is a 12-byte string set when the resource is created. However, clients should not make assumptions about the length and content of the Moid. The Moid should be treated as an opaque string.

Borrowing from database terminology, the Moid is a surrogate key, not a natural key. This means the Moid is not an attribute that exists in the real world like user assigned "name" or "serial number". The Moid is used as a primary key for the Managed Object. Because the Moid is a surrogate key, it is possible to rename objects without changing the URI of the Managed Object.

For example, the value of an Moid could be "59601f85ae84d80001dcc677".

Managed Object Uniform Resource Identifier (URI)

Each Managed Object can be addressed using a unique Uniform Resource Identifier (URI), which includes the Moid of the Managed Object. The URI can be used in any HTTP request to address the Managed Object.

The Intersight URI syntax consists of a hierarchical sequence of components referred to as the scheme, authority, path, and query. A generic Intersight URI is of the form:

https://intersight.com/path[?query]

The URI of a Managed Object comprises:

• The "https" scheme.
• An authority part, which must be set to the host "intersight.com". The API client must be able to resolve the intersight.com host name through DNS.
• A path, organized in hierarchical form, that appears as a sequence of segments separated by slashes.
• An optional query, separated from the preceding part by a question mark (?), containing a query string of non-hierarchical data. The syntax follows a subset of the ODATA specification. It is a sequence of attribute–value pairs separated by the "&" delimiter.

For example, the URI of an Object with Moid "59601f85ae84d80001dcc677" could be:

https://intersight.com/api/v1/asset/DeviceRegistrations/59601f85ae84d80001dcc677

URI fragments, as defined in RFC 3986, are currently not used for Intersight API queries. However, API client implementations should not assume the Intersight Web service will never include fragments.

Managed Object Tagging

Every class of Managed Object in the Intersight Information Model supports tagging. Tags enable you to categorize your managed objects with a scheme that you decide, such as by owner, environment, line of business, or geographic location. Tags can be set and queried through the Intersight API.

Each tag consists of a Key and an optional Value. The Key and Value are both string types. Intersight does not interpret the content of the tags. The JSON representation of the tags is an array of sub-documents, where each sub-document contains a Key and Value.

The JSON document below shows a sample representation of a Managed Object that has two tags, "Site" and "Owner".

{
  "Moid": "59601f8b3d1f1c0001c11d78",
  "ObjectType": "hyperflex.Cluster",
  "CreateTime": "2017-07-07T23:55:55.559Z",
  "ModTime": "2017-07-08T01:18:38.535Z",
  "Tags": [
    { "Key": "Site", "Value": "San Francisco"},
    { "Key": "Owner", "Value": "Bob"}
  ],
}

Supported Types in the Object Model Schema

All Managed Objects are structured data types that can be represented in JSON format. For example, if a field has an array value, the JSON array representation will be used:

{
  "field": [1, 2, 3]
}

The Intersight OpenAPI schema exposes fixed fields which have a declared name. Field values can be:

• Primitive data types, which are based on the types supported by the JSON Schema.
• Complex types, which are embedded structured data types composed of other types.
• Object Relationships (or Object References), which provide dynamic links to other Managed Objects.
• Arrays of any of the above types.

For example, a "hyperflex.Cluster" Managed Object can be represented with the following JSON document:

{
  "Moid": "59601f8b3d1f1c0001c11d78",
  "ObjectType": "hyperflex.Cluster",
  "CreateTime": "2017-07-07T23:55:55.559Z",
  "ModTime": "2017-07-08T01:18:38.535Z",
  "Owners": [
    "5948ad7704563a0001313f03",
    "59601f85ae84d80001dcc677"
  ],
  "AccountMoid": "5948ad7704563a0001313f03",
  "ClusterName": "HX-Hybrid-1",
  "ClusterUuid": "ed554be5-c9c5-4cec-b445-8396e554e56c",
  "ComputeNodeCount": 0,
  "ConvergedNodeCount": 4,
  "HypervisorVersion": "VMware ESXi 6.0.0 build-5050593",
  "Summary": {
    "activeNodes": "4 of 4",
    "address": "10.10.20.99",
    "boottime": 1499447235,
    "clusterAccessPolicy": "LENIENT",
    "compressionSavings": 18.516789173330594,
    "dataReplicationCompliance": "COMPLIANT",
    "dataReplicationFactor": "THREE_COPIES",
    "deduplicationSavings": 20.398526039013156,
    "freeCapacity": 8657612091774
  }
}

Object Relationships and Graph Structure

Managed Objects may include Object Relationships, which are dynamic links to REST resources. Intersight uses Hypermedia as the Engine of Application State (HATEOAS) conventions to represent Object Relationships.

Object Relationships can be links to self or links to other managed objects, which taken as a whole form a graph of objects.

The JSON representation of an Object Relationship is a "link" field. The value of the link field is a URI to an addressable REST resource that can be queried using an HTTP GET request. This makes it possible to manually or programmatically traverse a graph of Managed Objects.

Using relationships as a first-class attribute in the Intersight object model, many classes of graphs can be represented, including trees, cyclic graphs or bipartite graphs.

For example, the JSON document below shows a representation of an Object Reference to a "asset.DeviceRegistration" object.

{
  "Moid": "59696c5ea03d930001aa7b0a",
  "RegisteredDevice": {
    "ObjectType": "asset.DeviceRegistration",
    "Moid": "59601f85ae84d80001dcc677",
    "link": "https://intersight.com/api/v1/asset/DeviceRegistrations/59601f85ae84d80001dcc677"
  }
}

Policy Model Overview

The Intersight API defines an intent-based, declarative policy model. The policies specify the desired resulting state. The end user writes what they want, rather than what to do (in contrast to an imperative policy model).

• Intent is invariant : intent does not change when operational conditions change (such as server going up or down)
• Intent is portable : intent is abstracted from changes in the infrastructure or specific device specificities.
• Intent is composeable : the policies are extensible and allow disparate services developed independently to express their requirements.

The Intersight policy model is designed to support all UCS form factors (B series, C series standalone and FI/FEX attached, S series), and HyperFlex systems.