Subscriptions: Properties

Subscriptions: Properties

#340710

Description

The /subscriptions/<platformType>/properties resource is used to store a list of recommendation properties available to the Subscriptions resource for the purpose of filtering recommendations from the resulting subscription data set.

This resource acts as a catalog of recommendation properties to be referenced by the propertyReferences parameter in a subscription. Properties not defined in the /subscriptions/<platformType>/properties resource, cannot be referenced by a subscription property filter condition. See Subscriptions for details on defining a subscription and using property filter conditions.

There is a catalog for each supported <platformType>, which can only be referenced by the corresponding <platformType> subscription. For example, a container subscription (i.e. /subscriptions/containers) can only reference properties from the Container Subscriptions Properties catalog (i.e. /subscriptions/containers/properties).

Densify provides a default set of properties for each <platformType> catalog. You can extend these default sets by adding additional properties, or you can customize the sets by modify or deleting existing properties.

For the full set of available properties to add to the Cloud Subscriptions Properties catalog, refer to the cloud recommendation response schema:

See Default Cloud Properties for the list of default cloud properties.

Note: Some recommendation elements are not common to all technologies. It is good practice to indicate the technology for an element that is technology-specific in the aliasName (e.g. aliasName = "AWS minGroupRecommended"). This practice is helpful when you use the Cloud Subscriptions Properties catalog to form property conditions.

For the full set of available properties to add to the Container Subscriptions Properties catalog, refer to the container recommendation response schema:

See Default Container Properties for the list of default cloud properties.

Properties in the platform-specific Subscriptions Properties catalogs can be declared as global or private (i.e. user-specific). Global properties can be used by any API enabled user, while private properties can only be used by their owners. An exception to this rule is that administrative usersClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. have access to all properties - global or private user-specific.

Resource

/subscriptions/cloud/properties

/subscriptions/containers/properties

/subscriptions/properties

Note: If you use this resource without the <platformType> specified (i.e. without cloud or containers specified), the behavior is exactly the same as specifying the cloud-specific resource. This behavior enables backward compatibility with scripts using the Densify API prior to release 12.1.6, where the platform-specific indicator was not available.

Supported Operations

Table: Subscriptions Properties Supported Operations

HTTP Method

Input

Output

Description

GET /subscriptions/<platformType>/properties

Path Parameter:

Query String Parameter Options:

Collection of

Returns a list of existing properties in the platform-specific Subscriptions Properties catalog.

See Example: Getting a Collection of Private Cloud Subscriptions Properties.

GET /subscriptions/<platformType>/properties/<propertyRef>

Path Parameters:

Returns a Subscriptions property with unique identifier <propertyRef> from a platform-specific Subscriptions Properties catalog.

See Example: Getting a Specific Container Subscriptions Property.

POST /subscriptions/<platformType>/properties

Path Parameter:

Request Body Parameters:

Collection of

Collection of

Adds new recommendation properties into a platform-specific Subscriptions Properties catalog.

  • Administrative usersClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. can add global or private properties.
  • Non-administrative users can only add private properties.
  • propertyName is validated for uniqueness within a catalog (i.e. you cannot define two properties with the same propertyName).
  • aliasName is validated for uniqueness, depending on the private or global scope of the property (i.e. two users can use the same aliasName for their private property).
  • The properties bulk-add operation is committed as a whole unit. One property add error will roll back the entire bulk add operation.
  • Platform-specific properties must be added into the same platform-specific Subscriptions Properties catalog. For example, you can only add container properties into the Container Subscriptions Properties catalog.

See Example: Adding New Subscriptions Properties.

PUT /subscriptions/<platformType>/properties

Path Parameter:

Request Body Parameters:

Collection of

Collection of

Replaces parameters for existing properties in a platform-specific Subscriptions Properties catalog.

You must specify all parameters required for the property you want to update.

  • The <propertyRef> parameter is used to identify the property to update; hence it cannot be modified.
  • Only an administrative userClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. can change the owner parameter to promote a private property to a global property (i.e. set owner="").
  • If you are not an administrative user, you can only set the owner parameter to your username.
  • propertyName is validated for uniqueness within a catalog.
  • aliasName is validated for uniqueness, depending on the private or global scope of the property (i.e. two users can use the same aliasName for heir private property).
  • The bulk-edit operation is committed as a whole unit; an error resulting from one of the edits will roll back the entire bulk edit operation.

See Example: Modifying Subscriptions Properties

Note: If you are not an administrative user, you can only modify your own private properties.

PUT /subscriptions/<platformType>/properties/<propertyRef>

Path Parameters:

Request Body Parameters:

Replaces parameters in an existing property, identified by <propertyRef> in a platform-specific Subscriptions Properties catalog.

You must specify all parameters required for the existing property, as all previous parameters are deleted.

See Example: Modifying a Subscriptions Property.

Note: If you are not an administrative user, you can only modify your own private property.

DELETE /subscriptions/<platformType>/properties

Path Parameter:

Request Body Parameter:

Collection of

  • HTTP status of "204 No Content" if all delete operations are successful
  • If delete errors occur, then the following is returned for each property delete request:

Remove Subscriptions properties from a platform-specific Subscriptions Properties catalog.

See Example: Deleting Subscriptions Properties.

DELETE /subscriptions/<platformType>/properties/<propertyRef>

Path Parameter:

  • HTTP status of "204 No Content" if delete operation is successful
  • HTTP status of "404 Not Found" if property is not found
  • If the property is referenced by a subscription, then the following elements are returned:

Removes a Subscriptions property with <propertyRef> identifier from a platform-specific Subscriptions Properties catalog.

Parameters

Path Parameters

Table: Subscriptions Properties Path Parameters

Parameter Name

Type

Required (Y/N)

Description

platformType

string

Y

[cloud|containers]

Specify the technology platform for the Subscriptions property resource.

propertyRef

string

Y

Specify the unique identifier for a Subscriptions property.

Query String Parameters

Table: Subscriptions Properties Query String Parameters

Parameter Name

Type

Required (Y/N)

Description

type

string

 

Specify the type of Subscriptions properties to return:

  • all—Return all properties: global and private user-specific. If you are not an administrative userClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role., only private properties owned by you and global properties are returned. This is the default behavior if "type" is not specified in the request.
  • global—Return all global Subscriptions properties.
  • owner—Return user-specific Subscriptions properties. If you are not an administrative user, only private properties owned by you are returned. If you are an administrative user, all global and private properties are returned.

A Subscriptions property is considered global if the owner parameter is not populated. Global Subscriptions properties can be used by all Densify API users.

A Subscriptions property is considered private if the owner parameter contains a Densify username. Private Subscriptions properties can only be used by their owners or administrative users.

owner

string

 

If you are an administrative userClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role., you can specify a Densify username in conjunction with the type=owner query string parameter to return all of the specified user's private Subscriptions properties.

If you are not an administrative user, you can request for your own private properties. If you use the ?type=owner&owner=<anotherusername> query string option with a username other than your own, the returned response is a 400 Bad Request - "Current login user cannot query for owner" error.

Request Body Parameters

Table: Subscriptions Properties Request Body Parameters

Parameter Name

Type

Required (C-create/M-modify/D-delete)

Description

propertyRef

string

M D

Specify the unique identifier for a Subscriptions property.

propertyName

string

C M

Specify the recommendation element for the Subscriptions property.

The list of available recommendation elements can be found in the Response schema section of the Analysis: technology-specific Recommendations page. For example, refer to the Response schema section of the Analysis: AWS Recommendations for a full list of AWS recommendation elements.

The propertyName must be unique within a platform-specific Subscriptions Properties catalog.

aliasName

string

 

Specify an alias name for the Subscriptions property.

For global properties, the aliasName must be unique per platform-specific catalog. For private properties, the aliasName must be unique per owner and across all global Subscriptions properties per platform-specific catalog. For example, owner A and owner B can both have a private property alias named "OptimizedSize", as long as "OptimizedSize" is also not a global property alias within the same catalog.

owner

string

M1

When the owner parameter is not set, the Subscriptions property is considered global. Global Subscriptions properties can be used by all API users. Only administrative usersClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. can create global properties. When the owner parameter is set, the property is considered private. Private Subscriptions properties can only be used by their owners or administrative users.

If you are an administrative user, you have the ability to assign any Densify user as the owner of the Subscriptions property in a POST request. In a PUT request, administrative users can promote the property from private to global by setting owner: "".

If you are not an administrative user, you can only set the owner parameter to your Densify username. In a POST request, the owner parameter is automatically populated with your username.

Response

The following is a complete list of possible response elements returned for the /subscriptions/properties resource.

Table: Subscriptions Properties Response Schema

Element

Type

Filter/Sort

Description

propertyRef

string

 

The unique referenced ID of the Densify Subscriptions property.

propertyName

string

 

The Subscriptions property name.

aliasName

string

 

The Subscriptions property alias name.

owner

string

F

The designated owner of this Subscriptions property.

  • A Subscriptions property is considered global if this parameter is not populated.

  • A Subscriptions property is considered private if the owner parameter contains a Densify username.

message

string

 

The message for the status response.

status

number

 

The HTTP response code of the request. Possible status values include:

  • 200—success with request (usually with content in response body);
  • 204—success with request, no content returned;
  • 400—bad request (invalid parameters, logical errors);
  • 401—authentication failed;
  • 404—resource not found (or no privileges);
  • 415—unsupported media type;
  • 500—internal server error.

Ancillary Properties

The concept of core and ancillary properties is taken into consideration only for filtering purposes. Ancillary properties cannot stand alone in a Subscriptions property condition set; they must be used in conjunction with a core property for the purpose of filtering subscription returned results.

In any Subscriptions property condition set, you must have at least one core property condition. If you want to only filter subscription data based on an ancillary property, you can add an always-true condition with a core property.

Refer to Default Cloud Properties for the list of core and ancillary properties.

For example, if you want to see recommendations for systems that have been collected for over 10 days, create a property filter condition with auditInfo.dataCollection.auditCount > 10. Since auditInfo.dataCollection.auditCount is an ancillary property, you need to add another condition with a core property that would evaluate to true for the systems you are interested in, such as currentCost > 0 (the current cost of the instance is greater than 0). In this example, the Subscriptions property condition set would be:

propertyReferences =

  • (auditInfo.dataCollection.auditCount > 10)
  • (currentCost > 0)

Refer to Filter and Suppression Conditions for further details on how to define Subscriptions property conditions.

Default Cloud Properties

Default Container Properties

Examples

Example: Getting a Collection of Private Cloud Subscriptions Properties

The following example shows you how to retrieve a collection of your private cloud Subscriptions properties. This example assumes that your username is "saas".

Example: Getting a Specific Container Subscriptions Property

The following example shows you how to retrieve a specific container Subscriptions property with a known property reference ID. This property must be of type "global" or owned by you before a successful response is returned.

Example: Adding New Subscriptions Properties

This example shows you how to add new properties to the Cloud Subscriptions Properties catalog. Notice that the owner parameter is not set. If you are a non-administrative Densify user authenticating the POST request, the owner parameter is automatically set to your username. By having the owner parameter set, the property is considered private and can only be used by you (or any administrative user). If you are a Densify administrative userClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. and you do not set the owner parameter in the POST request, then the property is considered global.

If there is an error in the POST request resulting from any one of the property additions, then all the property additions in the request body are rolled back and not committed.

Example: Modifying Subscriptions Properties

The example below shows you how to modify two Subscriptions properties in the /subscriptions/cloud/properties resource catalog.

Observe the following behavior in the PUT request example:

  • propertyRef and propertyName parameters are mandatory for identifying the property to modify.
  • For both modification entries, the aliasName and owner parameters are updated.
  • You must be an administrative user to call the PUT request to update the owner parameter to an empty string. This promotes the property from private type to global type.

Example: Modifying a Subscriptions Property

This example shows you how to modify a single Subscriptions property using the /subscriptions/cloud/properties/<propertyRef> resource. This PUT request updates aliasName parameter for the specified property. The propertyName and owner parameters are mandatory in a PUT request.

Example: Deleting Subscriptions Properties

This example shows you how to delete a collection of properties from the /subscriptions/cloud/properties resource catalog.