Subscriptions: Tags

Subscriptions: Tags

#340720

Description

The /subscriptions/<platformType>/tags resource is used to store a list of system attributes available to the Subscriptions resource for the purpose of filtering systems from the resulting subscription data set.

This resource acts as a catalog of system attributes to be referenced by the tagReferences parameter in a subscription. System attributes not defined in a /subscriptions/<platformType>/tags resource, cannot be referenced by a Subscriptions tag filter condition. See Subscriptions for details on defining a subscription and using tag 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 tags from the Container Subscriptions Tags catalog(i.e. /subscriptions/containers/tags). Densify provides an initial default set of system attributes for each <platformType> catalog. You can extend these default sets by adding additional system attributes, or you can customize the sets by modify or deleting existing attributes. Only Densify standard attributes or technology-specific attributes (e.g. AWS, Containers) can be added to the platform-specific Subscriptions Tags catalogs. Contact your Cloud Advisor or support@Densify.com for a complete list of available Densify standard attributes. See Default Cloud Attribute Tags or Default Container Attribute Tags.

Attributes in the platform-specific Subscriptions Tags catalog can be declared as global or private (i.e. user-specific). Global attribute tags can be used by any API enabled user, whereas private attributes can only be used by their owners. Note that administrative usersClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. have access to both global and private attributes for all users.

Resource

/subscriptions/cloud/tags

/subscriptions/containers/tags

/subscriptions/tags

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 Tags Supported Operations

HTTP Method

Input

Output

Description

GET /subscriptions/<platformType>/tags

Path Parameter:

Query String Parameter Options:

Collection of

Returns a list of existing attributes from the platform-specific Subscriptions Tags catalog.

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

See Example: Getting a Collection of Container Subscriptions Tags.

GET /subscriptions/<platformType>/tags/<tagRef>

Path Parameters:

Returns an attribute tag with unique identifier <tagRef> from a platform-specific Subscriptions Tags catalog.

See Example: Getting a Specific Cloud Subscription Attribute Tag.

POST /subscriptions/<platformType>/tags

Path Parameter:

Request Body Parameters:

Collection of

Collection of

Adds new attributes into a platform-specific Subscriptions Tags catalog.

See Example: Adding New Subscription Attribute Tags.

PUT /subscriptions/<platformType>/tags

Path Parameter:

Request Body Parameters:

Collection of

Collection of

Replaces parameters from existing attribute tags in a platform-specific Subscriptions Tags catalog.

You must specify all parameters required for the tag you want to update, as all previous parameters are deleted (except <tagRef> since it is used to identify the attribute tag to update).

See Example: Modifying Subscription Attribute Tags.

PUT /subscriptions/<platformType>/tags/<tagRef>

Path Parameters:

Request Body Parameters:

Replaces parameters for an existing tag, identified by <tagRef>, in a platform-specific Subscriptions Tags catalog.

See Example: Modifying a Technology Subscription Attribute Tag.

DELETE /subscriptions/<platformType>/tags

Path Parameter:

Collection of

Request Body Parameter:

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

Deletes attribute tags from a platform-specific Subscriptions Tags catalog.

See Example: Deleting Subscription Attribute Tags

DELETE /subscriptions/<platformType>/tags/<tagRef>

Path Parameters:

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

Deletes attribute tag with <tagRef> identifier from a platform-specific Subscriptions Tags catalog.

See Example: Deleting a Single Subscription Attribute Tag

Parameters

Path Parameters

Table: Subscriptions Tags Path Parameters

Parameter Name

Type

Required (Y/N)

Description

platformType

string

Y

[cloud|containers]

Specify the technology platform for the Subscriptions attribute tag resource.

tagRef

string

Y

Specify the unique identifier for a Subscriptions attribute tag entry.

Query String Parameters

Table: Subscriptions Tags Query String Parameters

Parameter Name

Type

Required (Y/N)

Description

type

string

 

Specify the type of Subscriptions attribute tag to return:

  • all—Return all attribute tags: global and private user-specific. If you are not an administrative user, only private attribute tags owned by you and global attribute tags are returned. This is the default behavior if type is not specified in the request.
  • global—Return all global Subscriptions attribute tags.
  • owner—Return user-specific Subscriptions attribute tags. If you are not an administrative user, only private attribute tags owned by you are returned. If you are an administrative user, all global and private attribute tags are returned.

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

A Subscriptions tag is considered private if the owner parameter contains a Densify username. Private Subscriptions tags 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 attribute tags.

If you are not an administrative user, you can request for only your own private attribute tags. 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 Tags Request Body Parameters

Parameter Name

Type

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

Description

tagRef

string

M D

Specify the unique identifier for a Subscriptions attribute tag entry.

tagName

string

C M

Specify a unique name for a Subscriptions attribute tag entry.

For global Subscriptions attribute tags, the tagName must be unique within a platform-specific Subscriptions Tags catalog. For private Subscriptions attribute tags, the tagNames must be unique per owner and across all global Subscriptions attribute tags per platform-specific catalog. For example, owner A and owner B can both have a private attribute tag named "Bob", as long as "Bob" is not also a global attribute tag within the same platform-specific catalog.

attributeName

string

C M

Specify the attribute name for the Subscriptions attribute tag.

The attribute name must exist in the Densify standard set of system attributes. Contact support@Densify.com for a list of available system attributes.

Use the "Resource Tags" attribute name along with key and technology parameters for cloud technology-specific resource attributes in the "key:value" form. See Example: Adding New Subscription Attribute Tags for "Resource Tags" usage.

Use the "Container Labels" attribute name along with key and technology parameters for container-specific attributes in "key:value" form. See Default Container Attribute Tags for an example of "Container Labels" usage.

aliasName

string

 

Specify an alias name for the Subscriptions attribute tag.

For global attribute tags, the aliasName must be unique system-wide. For private attribute tags, the aliasName must be unique per owner and across all global Subscriptions attribute tags. For example, owner A and owner B can both have a private attribute tag alias named "Jane", as long as "Jane" is also not a global attribute tag alias.

key

string

CM1

Specify the key string required for the technology platform resource attribute.

If the Subscriptions tag is a reference to a resource attribute (i.e. "attributeName": "Resource Tags" or "attributeName": "Container Labels"), you need to specify both the key and technology elements for the specific resource attribute.

technology

string

CM2

Specify the technology platform for the resource attribute. Currently, the following technology platforms are supported:

  • AWS
  • CONTAINER

If the Subscriptions tag is a reference to a resource attribute (i.e. "attributeName": "Resource Tags" or "attributeName": "Container Labels"), you need to specify both the key and technology platform for the specific resource attribute.

owner

string

M3

When the owner parameter is not set, the Subscriptions tag is considered global. Global Subscriptions tags can be used by all API users, but can only be created by administrative usersClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role.. When the owner parameter is set, the tag is considered private. Private Subscriptions tags 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 tag in a POST request. In a PUT request, administrative users can promote the tag 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 that are returned for the /subscriptions/<platformType>/tags resource.

Table: Subscriptions Tags Response Schema

Element

Type

Filter/Sort

Description

tagRef

string

 

The unique referenced ID of the Densify Subscriptions attribute tag.

tagName

string

 

The Subscriptions attribute tag name.

attributeName

string

 

The attribute name for the Subscriptions attribute tag entry.

aliasName

string

 

The Subscriptions attribute tag alias name.

technology

string

 

The Subscriptions attribute tag technology platform.

key

string

 

The resource attribute key string for the associated technology platform.

owner

string

F

The designated owner of this Subscriptions attribute tag.

A Subscriptions attribute tag is considered global if this parameter is not populated. A Subscriptions attribute tag 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.

Default Cloud Attribute Tags

Default Container Attribute Tags

Examples

Example: Getting a Collection of Private Cloud Subscriptions Tags

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

Example: Getting a Collection of Container Subscriptions Tags

The following example shows you how to retrieve a collection of Subscriptions container attributes available to you.

Example: Getting a Specific Cloud Subscription Attribute Tag

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

Example: Adding New Subscription Attribute Tags

This example shows you how to add two new technology-specific attributes to the Cloud Subscriptions Tags 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 attribute entry 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 owner is not set, making the attribute entry global.

If there is an error in the POST request from any one of the attribute additions, then all the new attribute additions are rolled back.

Example: Modifying Subscription Attribute Tags

This example shows you how to modify two Subscriptions attribute tags in the Cloud Subscriptions Tags catalog.

Observe the following behavior in the PUT request example:

  • Even if you want to modify one parameter (e.g. aliasName) you still have to specify all parameters for the existing tag. A PUT request is essentially a DELETE and REPLACE operation.
  • This example assumes that you are an administrative userClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. to update a global tag (i.e. the first tag has "owner": "" , implying that it is a global tag).
  • tagName and aliasName are validated for uniqueness, depending on the private or global scope of the tags.
  • If there is an error in the PUT request from any one of the update entries, then all the updates are rolled back and not applied.

Example: Modifying a Technology Subscription Attribute Tag

This example shows you how to modify a single technology-specific Subscriptions attribute tag using the /subscriptions/cloud/tags/<tagRef> resource. This PUT request uses administrative privileges to update tagName and aliasName parameters for the specified tag.

Example: Deleting Subscription Attribute Tags

This example shows you how to delete a collection of attribute tags from the /subscriptions/cloud/tags resource catalog. Keep in mind that you can only delete your own private attribute tags from the catalog. Only administrative usersClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. can delete any global and any private attribute tags.

Example: Deleting a Single Subscription Attribute Tag

This example shows you how to delete a single attribute tags from the Cloud Subscriptions Tags catalog. Keep in mind that you can only delete your own private attribute tags from the catalog. Only administrative usersClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. can delete any global and any private attribute tags.