2.2.2 Common JSON Elements

Every resource that supports CRUD operations uses common JSON elements in any request or response. The following table summarizes the set of common URI parameters defined by this specification.

JSON Element

Type

Description

resourceId

Optional or Required

The resource ID is the identifier for the resource. The value MUST be unique in the context of the resource if it is a top-level resource, or in the context of the direct parent resource if it is a child resource.

When optional for ancestor resource, then required for descendant resource. See section 2.2.3.

resourceRef

Read-only Optional or Required

A relative URI to an associated resource.

See section 1.3.3.2.

instanceId

Read-only

This is the globally unique Id generated and used internally by the Network Controller. This value is a GUID in the form of XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. It is possible to do a reverse mapping from instanceId to resourceId with the internalResourceInstances resource, section 3.1.5.24. The instanceId element cannot be used directly in the API.

tags

Optional

Key-value pairs of arbitrary data that the client stores with the resource on the controller.

resourceMetadata

Optional

Structured data that the client provides to the server. This is an optional element, but it is suggested that all clients fill in the data that is applicable to them.

resourceMetadata.client

Optional

Indicates the client that creates or updates the resource. Although this element is optional, it is strongly recommended that it contain an appropriate value.

resourceMetadata.tenantId

Optional

The identifier of the tenant in the client environment. Provides linkage between the resource in the Network Controller and the tenant in the client network.

resourceMetadata.groupId

Optional

The identifier of the group that the tenant belongs to within the client environment. This is usually used in environments that contain multiple tenants that are aggregated into groups that the client manages. This provides linkage between the resource in the Network Controller and the group that the tenant belongs to in the client network.

resourceMetadata.resourceName

Optional

Indicates the globally unique name of the resource. If it is not assigned a value, then it will be blank.

resourceMetadata.originalHref

Optional

The original URI of the resource if the client uses a URI based system to organize resources.

properties

Optional

Array of structured data. The structure of this data is unique to each resource except two common read-only elements - etag and provisioningState.

properties.etag

Read-only

An opaque string representing the state of the resource at the time the response was generated. This header is returned for requests that target a single entity. The Network Controller will also always return an etag in the response body. The etag is updated every time the resource is updated.

properties.provisioningState

Read-only

Indicates the various states of the resource. Valid values are Deleting, Failed, Succeeded, and Updating.