Web service object model

This topic describes the Delphix object model as exported over the web services.

Object types

All objects in the Delphix API are "typed objects." All such objects have a type field that indicates the type of the object and its associated semantics. This allows for object inheritance and polymorphism without requiring separate APIs for each type and allows generic client-specific semantic encoding and decoding without having to be aware of the context. This means that even APIs that operate only a specific type (such as the Group API) still require a type field to be specified as part of the input, and will continue to report the type of objects when listing or retrieving objects. This allows the APIs to evolve in a backward-compatible fashion through the introduction of new types.

Certain "root" object types (groups, containers, sources, etc) have an associated API. This API is rooted at a particular point under /resources/json/delphix, but all APIs follow a standard format beneath this namespace. The CLI namespace is a direct reflection of this URL, and the API reference has an index both by object type as well as by object (CLI) path. These APIs may operate on different extended types (such as OracleSIConfig and OracleRACConfig), but the base operations remain the same regardless of input type.

Object references

Some objects returned by the APIs are pure typed objects, in that they don't represent the persistent state on the Delphix Engine but are rather calculated and returned upon request. Most of the objects in the system, however, are "persistent objects." Persistent objects (of type PersistentObject) have a stable reference that uniquely identifies the object on the system. This reference is separate from its name so that objects can be renamed without affecting the programmatic API. More information about object names and how they can be represented generically can be found in the CLI documentation. Object references are opaque tokens; while they can be stored and reused for later use, and interpretation of their contents is unstable and may break in a future release.

The Delphix object hierarchy is stitched together by these object references. When fetching an object that refers to another object, the member will be returned as a reference, rather than being inserted directly within the parent object. This allows consumers to control when and how links are resolved and make it clear when an object may change independently from its parent. The per-object APIs outlined below all operate on object references.

Note that some Delphix objects are singleton objects, and there is only one such object on the system. These objects do not have references because the API URL uniquely identifies the object on the system.

API operations

All APIs optionally support the following operations:

• CREATE - Create a new instance of the given object type. This is used for most objects, but more complicated objects, such as dSources and VDBs, must be created through a dedicated link or provision operation. The input to this operation is typically the object itself, though some objects may have specialized parameters used during the creation of objects. An example of this is  HostEnvironmentCreateParameters.

• UPDATE - Update properties of the given object, specified as an object reference in the URL.

• DELETE - Delete a particular object, specified as an object reference in the URL. These operations are typically done as HTTP DELETE operations, but it is also possible to do a POST operation to the /delete API to do the same thing. The POST form allows for delete-specific parameters, such as OracleDeleteParameters.

• GET - Get the properties for a particular object, specified as an object reference in the URL.

• LIST - List all objects of the given type within the system. These APIs typically take optional query parameters that allow the set of results to be constrained, filtered, paginated, or sorted.

In addition, the following non-CRUD operations may be supported:

• Root Operation - A POST or GET operation to the root of an API namespace, not associated with a particular object. This can be used for singleton objects, such as NDMPConfig, operations that create objects, such as link, and operations that operate on multiple objects at once.

• Per-object Operation - A POST operation to a particular object reference. These operations are typically read-write but are not required to be so. These would include read-only operations that cannot be modeled as CRUD operations or require complex input use per-object operations.

Database object mModel

In order to support a wide variety of databases and database configurations, the database object model is more complex than it may initially appear after having used the Delphix Management application. For example, there is no such thing as a "dSource" or "VDB" object, only data "containers" with attached "sources". More information about how Database objects are modeled within Delphix can be found in the CLI documentation

Asynchronous execution

All APIs are designed to be transactionally safe and "quick." However, there are operations that may take a long period of time or may need to reach out to external hosts or databases such that they cannot be done safely within the context of a single API call. Such operations will dispatch a Job to handle asynchronous execution of the operation. Any API can potentially spawn a job, and which APIs spawn jobs and which do not may differ between object types or releases. If you are developing a full-featured automation system, it is recommended that you build a generic infrastructure to handle job monitoring, rather than encoding the behavior of particular APIs that may change over time.

Every operation, except for LIST and GET, which are guaranteed to be read-only, can potentially spawn a job. This is represented by the job field of the APIResult object. If this field is null, then the action can be completed within the bounds of the API call. Otherwise, a reference to a dispatched job is returned.

Jobs can spawn other jobs for especially complex operations, such as provisioning to an Oracle cluster environment. The job returned in the API invocation is the root job, and overall success or failure of the operation is determined by the state of this job. Some operations may succeed even if a child job fails. An example would be provisioning to an Oracle cluster where one node failed, but others were successful.

Progress can be monitored by examining the JobEvent objects in the Job object returned through the job API.