Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
222 lines (200 sloc) 6.94 KB

{{{ "title": "Get Group", "date": "10-15-2014", "author": "Richard Seroter", "attachments": [] }}}

Gets the details for a individual server group and any sub-groups and servers that it contains. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to identify the servers in a particular group, retrieve a group hierarchy, or get links to information (e.g. billing, monitoring, scheduled activities) about a group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0

Request

URI Parameters

Name Type Description Req.
AccountAlias string Short code for a particular account. Yes
GroupID string ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal. Yes

Response

Group Entity Definition

Name Type Description
id string ID of the group being queried
name string User-defined name of the group
description string User-defined description of this group
locationId string Data center location identifier
type string Group type which could include system types like "archive"
status string Describes if group is online or not
serversCount integer Number of servers this group contains
groups array Refers to this same entity type for each sub-group
links array Collection of [entity links](../Getting Started/api-v20-links-framework.md) that point to resources related to this group
changeInfo complex Describes "created" and "modified" details
customFields complex Details about any custom fields and their values

ChangeInfo Definition

Name Type Description
createdDate dateTime Date/time that the group was created
createdBy string Who created the group
modifiedDate dateTime Date/time that the group was last updated
modifiedBy string Who modified the group last

CustomFields Definition

Name Type Description
id string Unique ID of the custom field
name string Friendly name of the custom field
value string Underlying value of the field
displayValue string Shown value of the field

Examples

JSON

{
  "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "name": "Web Applications",
  "description": "public facing web apps",
  "locationId": "WA1",
  "type": "default",
  "status": "active",
  "serversCount": 2,
  "groups": [
    {
      "id": "31d13f501459411ba59304f3d47486eb",
      "name": "Training Environment",
      "description": "Temporary servers",
      "locationId": "WA1",
      "type": "default",
      "status": "active",
      "serversCount": 0,
      "groups": [],
      "links": [
        {
          "rel":"createGroup",
          "href":"/v2/groups/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel":"createServer",
          "href":"/v2/servers/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel": "self",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb",
          "verbs":[
            "GET",
            "PATCH",
            "DELETE"
          ]
        },
        {
          "rel": "parentGroup",
          "href": "/v2/groups/acct/231c3f3fec0e46499290b351199d555f",
          "id": "231c3f3fec0e46499290b351199d555f"
        },
        {
          "rel": "defaults",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/defaults",
          "verbs":[
            "GET",
            "POST"
          ]
        },  
        {
          "rel": "billing",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/billing"
        },
        {
          "rel": "archiveGroupAction",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/archive"
        },
        {
          "rel": "statistics",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/statistics"
        },
        {
          "rel":"upcomingScheduledActivities",
          "href":"/v2/groups/acct/8a03fcae8dd65411b05f00505682315a/upcomingScheduledActivities"
        },
        {
          "rel":"horizontalAutoscalePolicyMapping",
          "href":"/v2/groups/acct/31d13f501459411ba59304f3d47486eb/horizontalAutoscalePolicy",
          "verbs":[
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel": "scheduledActivities",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/scheduledActivities"
          "verbs":[
            "GET",
            "POST"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel": "self",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "parentGroup",
      "href": "/v2/groups/acct/540494152d0c4a9ab61869562b4c1471",
      "id": "540494152d0c4a9ab61869562b4c1471"
    },
    {
      "rel": "billing",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/billing"
    },
    {
      "rel": "archiveGroupAction",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/archive"
    },
    {
      "rel": "statistics",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/scheduledActivities"
    },
    {
      "rel": "server",
      "href": "/v2/servers/acct/wa1acctpre7101",
      "id": "WA1ACCTPRE7101"
    },
    {
      "rel": "server",
      "href": "/v2/servers/btdi/wa1acctpre7202",
      "id": "WA1ACCTPRE7202"
    }
  ],
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "customFields": [
    {
      "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
      "name": "Cost Center",
      "value": "IT-DEV",
      "displayValue": "IT-DEV"
    },
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "name": "CMDB ID",
      "value": "1100003",
      "displayValue": "1100003"
    }
  ]
}