Groups REST API

• Description – these interfaces allow users to retrieve information on groups, create, delete, and update groups

• Request URL – GET /ufmRest/app/groups

• Main operationsGet all groupsGet a group using its nameUpdate a group using its nameDelete a group using its nameCreate a groupAdd members to a groupRemove members from a group

Get All Groups

• Description – retrieve information on groups

• Request URL – GET /ufmRest/resources/groups

• Request Content Type – Application/json

• Response 

  [
       {
       "description": "grp222", 
       "type": "Rack", 
       "severity": "Info", 
       "name": "grp2" 
       },
  
       {
       "description": "grp111", 
       "type": "Rack", 
       "severity": "Info", 
       "name": "grp1"
       }
  ]
  

• Possible Filters

  • Type – filters by type. Example: 

    /ufmRest/resources/groups?type=Rack
    

    Possible values: “Rack”, “General”, “Port”

  • Members – adds members to the response. Example:

    ufmRest/resources/groups?type=Rack&members=true
    

  • extend_members 

    
    

    /resources/groups?members=true&extend_members=true
    

  • device_id 

    /resources/groups?device_id=0008f10001085600
    

• Response: 

  [ 
       { 
       "description": "grp222", 
       "type": "Rack", 
       "severity":"Info", 
       "members": [ "0002c90300a7ccf0", "0002c9030060dc20"],
       "name": "grp2" 
       },
  
       { 
       "description": "grp111", 
       "type": "Rack", 
       "severity": "Info",
       "members": [ "0002c903007e50a0" ], 
       "name": "grp1" 
       }
  ]
  

• Status Codes

  • 200 – OK

Get Group Using Its Name

• Description – Retrieve information on a group using its name

• Request URL – GET ufmRest/resources/groups/<group_name>

• Request Content Type – Application/json

• Response 

  [ 
       { 
       "description": "grp111", 
       "type": "Rack", 
       "severity": "Info", 
       "name": "grp1" 
  	 } 
  ]
  

• Possible Filters

• Members – adds members to the response. Example: 

  /ufmRest/resources/groups/grp1?members=true
  

• Status Codes

  • 200 – OK

Update Group Using Name

• Description – update a group using its name

• Request URL – PUT ufmRest/resources/groups/<group_name>

• Request Content Type – Application/json

• Request Data

  {
    "description*": "new_desc"
  }
  

  *This is the only attribute that can be updated.

• Status Codes

  • 200 – OK

  • 400 – BAD REQUEST

Delete Group Using Name

• Description – delete a group using its name

• Request URL – DELETE ufmRest/resources/groups/<group_name>

• Request Content Type – Application/json

• Request Data – N/A

• Status Codes

  • 202 – accepted

Create Group

• Description – create a new group

• Request URL – POST ufmRest/resources/groups/

• Request Content Type – Application/json

• Request Data

  {
    "description*": "new_desc",
    "type**": "group_type",
    "name***": "group_name"
  }
  

  * Optional attribute.

  ** Mandatory attribute. Can only be “Rack” or “General”, “Port”.

  *** Mandatory attribute.

• Status Codes

  • 201 – created with the link to the group object

  • 400 – BAD REQUEST

Add Members to Group

• Description – add members to an existing group

• Request URL – POST /ufmRest/resources/groups/<group_name>/members

• Request Content Type – Application/json

• Request Data 

  {
    "object_ids": ["0002c90300a7ccf0", "0002c9030060dc20"]
  }
  

• Status Codes

  • 202 – accepted

  • 400 – BAD REQUEST

Remove Members From Group

• Description – remove members from an existing group

• Request URL – DELETE /ufmRest/resources/groups/<group_name>/members

• Request Content Type – Application/json

• Request Data

  {
    "object_ids": ["0002c90300a7ccf0", "0002c9030060dc20"]
  }
  

• Note – to remove all members of a group, the object_ids argument in the request data can be left empty

• Status Codes

  • 202 – accepted

Apply Software Upgrade or Firmware Upgrade Action

• Description – allows user to apply software upgrade action on group of switches or firmware upgrade action on group of hosts.

• Request URL – POST /ufmRestV2/actions

• Request Content Type – Application/json

• Request Data

  {
    "params": {
      "username": "admin",
      "password": "admin",
      "path": "/tmp",
      "image": "software_upgrade.img",
      "protocol": "ftp",
      "server": "10.20.30.40"
    },
    "description": "",
    "action": "sw_upgrade",
    "object_ids": [
      "host"
    ],
    "object_type": "Group",
    "identifier": "id"
  }
  

• Status Codes202 – accepted400 – bad request404 – not found

Last updated: July 09, 2021