NVIDIA NEO REST API Guide v2.7.20
NVIDIA NEO REST API Guide v2.7.20

Groups

Description

This REST API allows users to access various groups data in NEO

Request URL

http://<NEO_SERVER_ADDRESS>/neo/resources/groups

Main Operations

  • Get All Groups

  • Get Groups

  • Create Group

  • Update Group

  • Delete Group

  • Add Members to Group

  • Get members in Group

  • Get systems with properties in Group

  • Delete Members from Group

  • Delete

  • All Members in Group

  • Get Groups by Members

  • Get All Available Systems for All Groups

  • Get Groups by Type

Description

Get all available groups

Request URL

GET /neo/resources/groups

Request Data

N/A

Response:

One group:

Copy
Copied!
            

[{ "groupType": "System", "elementName": "group1", "description": "", "instanceID": "group.group1 ", "hasSettings": false, "readOnly": false } ]

Multiple groups:

Copy
Copied!
            

[{ "groupType": "System", "elementName": "group1", "description": "", "instanceID": "group.group1 ", "hasSettings": false, "readOnly": false }, { "groupType": "System", "elementName": "group2", "description": "", "instanceID": "group.group2", "hasSettings": false, "readOnly": false } ]

Warning

Result Data includes custom groups created by users & global groups that are a part of NEO by default.

Description

Retrieves a specific set of groups

Request URL

  • Get System Groups: neo/resources/groups/<group_name>

  • Get Port Groups: neo/resources/groups/group1, group2, …

Request Data

N/A

Response:

One group:

Copy
Copied!
            

{ "elementName": "group1", "instanceID": "group.group1 ", "groupType": "System", "description": "", "hasSettings": false, "readOnly": false }

Multiple groups:

Copy
Copied!
            

[{ "elementName": "group1", "instanceID": "group.group1 ", "groupType": "System", "description": "", "hasSettings": false, "readOnly": false }, { "elementName": "group2", "instanceID": "group.group2 ", "groupType": "System", "description": "", "hasSettings": false, "readOnly": false } ]

Description

This interface is used to add a group

Request URL

POST /neo/resources/groups

Request Data

{ "elementName": "custom_group1", "description": "NEOcustom group", "groyp_type": "System" }

Response

URI: /neo/resources/groups/custom_group1

Warning
  • Group should have a unique name as an identifier

  • Group description is optional

Description

Update an existing group

Request URL

PUT /neo/resources/groups/<group_name>

Request Data

{ 

"description": "updated description"

}

Response

""

Description

Remove an existing group

Request URL

DELETE /neo/resources/groups/<group_name>

Request Data

N/A

Response

Location header includes a URI with a Job ID for group deletion

Status Codes

Note: Status code "202 ACCEPTED" means that an asynchronous job has been created and that the job ID has been returned into the location header

Description

Add a member as members to custom groups

Request URL

POST /neo/resources/groups/<group_name>/members

Response

  • Response header includes a location header with URI for the added members: /neo/resources/groups/<group_name>/members/<member_IP>

  • Response for add system members: /neo/resources/groups/<group_name>/members/10.0.0.1.system, 10.0.0.2.system

  • Response for add network port members: /neo/resources/groups/<group_name>/members/10.0.0.1.network_port.eth1.2, 10.0.0.2. network_port.eth1.3

Status Codes

Note: Status code "403 FORBIDDEN" could be due to the following:

  • The specified group is a global group

  • Certain systems are being assigned to multiple groups for which access credentials are set

Request Data:

Copy
Copied!
            

[ "<first_system_IP>.system", "<_second_system_IP>.system", … ]

Add System members

Copy
Copied!
            

[ "10.0.0.1.system", "10.0.0.2.system" ]

Add network port members

Copy
Copied!
            

[ "10.0.0.1.network_port.eth1.2", "10.0.0.2.network_port.eth1.3" ]

Warning
  • Members can be added to a group of the same type only (a system member can be added to a system group, and network port members can be added to network port groups)

  • Any member can be added to multiple groups at the same time

  • A system can only be a member of one group for which access credentials are set

Description

Retrieve all systems that are members of the specified group

Request URL

GET /neo/resources/groups/<group_name>/members

Request Data:

System members:

Copy
Copied!
            

[{ "status": "Pending Reboot", "profile": "Eth Single Switch", "mlag": { "iplLag": "Po2", "name": "", "macAddress": "00:00:5E:00:01:00", "virtualIp": "192.168.1.1/24", … }, "vendor": "Mellanox", "macAddress": "24:8A:07:81:B0:80", "swVersion": "X86_64 VERIFICATION_3.6.5961-41 2018-02-20 16:53:59 x86_64", "id": "10.209.36.162.system", "statusDescriptions": [ "Pending Reboot Due to SW Upgrade" ], "healthState": "OK", "name": "r-ufm-sw75", "sysType": "Mellanox Switch", "caption": "MLNX-OS", "model": "MSN2100", "ipAddress": "10.209.36.162", "isManagement": true }, { "status": "Communication OK", "profile": "Eth Single Switch", "mlag": null, "vendor": "Mellanox", "macAddress": "N/A", "swVersion": "X86_64 3.6.5000 2017-11-10 18:14:32 x86_64", "id": "10.209.36.161.system", "statusDescriptions": [], "healthState": "OK", "name": "r-ufm-sw74", "sysType": "Mellanox Switch", "caption": "MLNX-OS", "model": "MSN2100", "ipAddress": "10.209.36.161", "isManagement": true }

Network port members:

Copy
Copied!
            

[{ "instanceID": "10.0.0.1.networkport.eth1.1" }, { "instanceID": "10.0.0.2.networkport.eth1.2" } ]

Description

Used to retrieve systems and specify additional system properties (not just instanceID which is returned by default) from a specified custom group.

Request URL

GET /neo/resources/groups/<group_name>/members?props=<list_of_properties>

Where <list_of_properties> includes comma supported properties as they appear in NEO

Request Data

N/A

Response

[
    {
        "id": "<system_IP>.system",
        "<property_1>": "prop_value",
    }
]

Example (specifying 2 system properties: status and name):

GET /neo/resources/groups/<group_name>/members?props=status,name

Result:

Copy
Copied!
            

[{ "instanceID": "10.0.0.1.system", "status": "OK", "name": "switch" } ]

Warning

The supported system properties are the ones that are returned from "Get Members in Group."

Description

Remove members from a custom group.

Request URL

DELETE /neo/resources/groups/<group_name>/members

Response

N/A (No Content)

Status Codes

Note: Status code "204 NO CONTENT" means that the system was removed from the group

Request Data:

System group:

Copy
Copied!
            

["10.0.0.1. system", "10.0.0.2. system" ]

Network port group:

Copy
Copied!
            

[ "10.0.0.1. network_port.eth1.1", "10.0.0.2. network_port.eth1.2" ]

Warning

Users can remove multiple members from one group at the same time by adding the member IDs as a list in the request body.

Description

Remove all members from a custom group

Request URL

DELETE /neo/resources/groups/<group_name>/members

Request Data

N/A

Response

N/A (No Content)

Status Codes

Note: Status code "204 NO CONTENT" means that member was removed from the group

Description

Used to retrieve groups by specifying a member ID that is a member of those groups

Request URL

GET /neo/resources/groups?member=<member_IP>

  • System member: GET /neo/resources/groups?member=<system_IP>.system

  • Network port member: GET /neo/resources/groups?member=<system_IP>.network_port.eth1.2

Request Data

N/A

Example

(system: 10.0.0.1; where system is a member of a group: test_group)

GET /neo/resources/groups?member=10.0.0.1.system

Result

[

{

elementName: "test_group"

instanceID: "group.test_group"

description: ""

generation: -1

hasSettings: false

caption: ""

}

]

Note: The result will contain a list of groups, since any member (system/port) can be a member of multiple groups at the same time.

Response:

System member:

Copy
Copied!
            

[{ "groupType": "System", "elementName": "group1", "description": "", "instanceID": "group.group1 ", "hasSettings": false, "readOnly": false } ]

Network port member:

Copy
Copied!
            

[{ "groupType": "NetworkPort", "elementName": "group1", "description": "", "instanceID": "group.group1 ", "hasSettings": false, "readOnly": fals } ]

Description

This API gets all available systems for all groups

Request URL

GET neo/resources/groups/members/available

Request Data

N/A

peerIplIp

peerIplIp

The IP of the peer in the IPL

peerMgmtIp

The management IP of the peer system

iplLag

IPL LAG identifier

localIplIp

The IP of the device in the IPL

role

The role of the system in the MLAG Can be either master/standby

Response:

Copy
Copied!
            

[{ "status": "Communication OK", "profile": "Eth Single Switch", "healthState": "OK", "mlag": { "peerIplIp": "10.10.10.2", "peerMgmtIp": "10.224.15.90", "iplLag": "", "macAddress": "00:00:5E:00:01:5D", "virtualIp": "10.10.10.254/24", "localIplIp": "10.10.10.1", "adminState": "Disabled", "role": "master", "vlanInterface": "4000", "operationalState": "Down", "id": "10.224.15.89.mlag.1", "name": "" }, "vendor": "Mellanox", "name": "ufm-switch19", "ipAddress": "10.224.15.89", "swVersion": "X86_64 3.6.3130 2017-02-27 18:57:09 x86_64", "id": "10.224.15.89.system", "caption": "Mellanox Onyx", "model": "MSN2700", "sysType": "Mellanox Switch", "isManagement": true }, { "status": "Communication OK", "profile": "Eth Single Switch", "healthState": "OK", "mlag": null, "vendor": "Mellanox", "name": "ufm-switch20", "ipAddress": "10.224.15.90", "swVersion": "X86_64 3.6.1002 2016-06-09 20:24:31 x86_64", "id": "10.224.15.90.system", "caption": "Mellanox Onyx", "model": "MSN2700", "sysType": "Mellanox Switch", "isManagement": true } ]

Description

Retrieves a set of group by type

Request URL

  • Get System Groups: neo/resources/groups?group_type=System

  • Get Port Groups: neo/resources/groups?group_type=NetworkPort

Request Data

N/A

Response:

System groups:

Copy
Copied!
            

[{ "groupType": "System", "elementName": "systemGroup1", "description": "", "instanceID": "group.systemGroup1 ", "hasSettings": false, "readOnly": false }, { "groupType": "System", "elementName": "systemGroup2", "description": "", "instanceID": "group.systemGroup2", "hasSettings": false, "readOnly": false } ]

Network port groups:

Copy
Copied!
            

[{ "groupType": "System", "elementName": "systemGroup1", "description": "", "instanceID": "group.systemGroup1 ", "hasSettings": false, "readOnly": false }, { "groupType": "System", "elementName": "systemGroup2", "description": "", "instanceID": "group.systemGroup2", "hasSettings": false, "readOnly": false } ]

© Copyright 2023, NVIDIA. Last updated on Nov 16, 2023.