REST API Examples

---

In general, you should not enclose numerical values such as port numbers in curly quotes. Otherwise, each parameter and value is enclosed by curly quotes, as shown in the examples.

You should also have copies of the

• Pluribus Networks Netvisor ONE Configuration Guide
• Pluribus Networks Netvisor ONE Command Reference A-O
• Pluribus Networks Netvisor ONE Command Reference P-Z

available here to identify the parameters used by each command.

Using Swagger and REST API Examples

You can try out the following examples in the Swagger UI to ensure that they work on your server-switch.

The following Request methods are supported:

• GET – Retrieves data from the specified object.
• PUT – Adds the supplied information to the specified object; returns a 404 Resource Not Found error if the object does not exist.
• POST – Creates the object with the supplied information.
• DELETE – Deletes the specified object.

---

Example 1: Get a vFlow identified by name:

GET /vflows/name/asdasd (where the name of the vFlow is asdasd)

 

Request URL

 

http://10.110.0.56:80/vRest/vflows/name/asdasd

 

Response Body

 

{"vflow":{"name":"asdasd","id":"c000184:52","scope":"local","type":"vflow","hidden":false,"burst-size":0,"precedence":2,"log-stats":true,"stats-interval":60,"hw-stats":true,"enable":true,"table-name":"System-L1-L4-Tun-1-0"}}

{"result":{"api.switch-name":"local","scope":"local","status":"Success","code":0,"message":""}}

 

Response Code

200

Response Headers

{

  "Content-Type": "application/x-ndjson"

}

---

Example 2: Get a vFlow identified by ID:

GET /vflows/id/ce46fb (where the id of the vflow is c000184:52)

Request URL

http://10.110.0.56:80/vRest/vflows/id/c000184%3A52

 

Response Body

 

{"vflow":{"name":"asdasd","id":"c000184:52","scope":"local","type":"vflow","hidden":false,"burst-size":0,"precedence":2,"log-stats":true,"stats-interval":60,"hw-stats":true,"enable":true,"table-name":"System-L1-L4-Tun-1-0"}}{"result":{"api.switch-name":"local","scope":"local","status":"Success","code":0,"message":""}}

 

Response Code

200

Response Headers

{

  "Content-Type": "application/x-ndjson"

}

---

Example 3: Create a vFlow:

POST /vflows {

  "name": "techpubs",

  "scope":"local",

  "burst-size":0,

  "precedence":2,

  "ether-type":"ipv4",

  "src-port":22,

  "dst-port":67,

  "src-ip":"10.110.0.48",

  "dst-ip":"10.110.0.50",

  "proto":1,

  "action":"copy-to-cpu"

}

---

Note: The last line of the script should not contain a final comma. If you do not remove the comma, you may see a Response Body error such as: "There was a problem parsing the JSON input. Please check the JSON syntax and verify that the field values are the correct type."

---

Request URL

http://10.110.0.48:80/vRest/vflows

Response Body

{

  "result": {

    "status": "Success",

    "result": [

      {

        "api.switch-name": "local",

        "scope": "local",

        "status": "Success",

        "code": 0,

        "message": ""

      }

    ]

  }

}

Response Code

201

Response Headers

{

  "Content-Type": "application/json"

}

---

Example 4: Delete a vFlow.

DELETE /vFlow (where the name of the vFlow is techpubs)

 

{

  "status": "",

  "result": [

    {

      "api.switch-name": "",

      "scope": "",

      "status": "",

      "code": 0,

      "message": ""

    }

  ]

}

 

Request URL

 

http://10.110.0.48:80/vRest/vflows/name/techpubs

 

Response Body

 

{"result":{"api.switch-name":"local","scope":"local","status":"Success","code":0,"message":""}}

 

Response Code

200

Response Headers

{

  "Content-Type": "application/x-ndjson"

}

---

Example 5: Obtaining User Role information:

The REST service, in general, doesn't chase references since the REST client can easily do so using multiple REST API calls.

Here is how to get the role information starting from a user's roles.

1. GET /users/user1/roles (where user1 is network-admin)

Request URL

http://10.110.0.48:80/vRest/users/network-admin/roles

Response Body

{

  "data": [

    {

      "role-id": "0:0"

    }

  ],

  "result": {

    "status": "Success",

    "result": [

      {

        "api.switch-name": "local",

        "scope": "local",

        "status": "Success",

        "code": 0,

        "message": ""

      }

    ]

  }

}

Response Code

200

Response Headers

{

  "Content-Type": "application/json"

}

2. GET /roles

Request URL

http://10.110.0.48:80/vRest/roles

Response Body

{

  "data": [

    {

      "id": "0:0",

      "name": "network-admin",

      "scope": "local",

      "vnet-id": "0:0",

      "access": "read-write",

      "running-config": true,

      "shell": true,

      "sudo": false,

      "group-id": 20000

    },

    {

      "id": "0:1",

      "name": "read-only-network-admin",

      "scope": "local",

      "vnet-id": "0:0",

      "access": "read-only",

      "running-config": false,

      "shell": false,

      "sudo": false,

      "group-id": 20001

    } ],

  "result": {

    "status": "Success",

    "result": [

      {

        "api.switch-name": "local",

        "scope": "local",

        "status": "Success",

        "code": 0,

        "message": ""

      }

    ]

  }

}

Response Code

200

Response Headers

{

  "Content-Type": "application/json"

}

3. Match Role from first result set to ID from the second result set.

---

Example 6: Update a User Role:

PUT /roles/name (where name is techpubs_security_role and change the role to read-write access)

{

  "access": "read-write",

  "shell": false,

  "sudo": false,

  "running-config": false,

  "delete-from-users": false

}

Request URL

http://10.110.0.48:80/vRest/roles/techpubs_security_role

Response Body

{

  "result": {

    "status": "Success",

    "result": [

      {

        "api.switch-name": "local",

        "scope": "local",

        "status": "Success",

        "code": 0,

        "message": ""

      }

    ]

  }

}

 

Response Code

200

Response Headers

{

  "Content-Type": "application/json"

}

---

Example 7: Create and review a VLAN:

To create the VLAN:

POST /vlans

{

  "scope": "local",

  "id": 1411,

  "description": "techpubs-1"

}

Request URL

http://10.110.0.48:80/vRest/vlans

Response Body

{

  "result": {

    "status": "Success",

    "result": [

      {

        "api.switch-name": "local",

        "scope": "local",

        "status": "Success",

        "code": 0,

        "message": "Vlans 1411 created"

      }

    ]

  }

}

Response Code

201

Response Headers

{

  "Content-Type": "application/json"

}

To review the VLAN:

GET /vlans/id/{id} (where id = 1411)

{

  "data": [

    {

      "api.switch-name": "",

      "vnet-id": "",

      "id": 0,

      "type": "",

      "scope": "",

      "active": false,

      "stats": false,

      "flags": "",

      "hw-vpn": 0,

      "hw-mcast-group": 0,

      "repl-vtep": "",

      "vrg-id": "",

      "send-ports": "",

      "active-edge-ports": "",

      "ports-specified": false,

      "hw-member-ports": "",

      "public-vlan": 0,

      "vxlan": 0,

      "auto-vxlan": false,

      "vxlan-mode": "",

      "replicators": "",

      "ports": "",

      "untagged-ports": "",

      "description": ""

    } ],

  "result": {

    "status": "",

    "result": [

      {

        "api.switch-name": "",

        "scope": "",

        "status": "",

        "code": 0,

        "message": ""

      }

    ]

  }

}

Parameters

id = 1411

Request URL

http://10.110.0.48:80/vRest/vlans/id/1411

Response Body

{

  "data": [

    {

      "id": 1411,

      "type": "public",

      "auto-vxlan": false,

      "hw-vpn": 0,

      "hw-mcast-group": 0,

      "repl-vtep": "0:0:0:0:0:0:0:0",

      "scope": "local",

      "description": "techpubs-1",

      "active": true,

      "stats": true,

      "vrg-id": "0:0",

      "ports": "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,272,273,274",

      "untagged-ports": "",

      "active-edge-ports": ""

    }

  ],

  "result": {

    "status": "Success",

    "result": [

      {

        "api.switch-name": "local",

        "scope": "local",

        "status": "Success",

        "code": 0,

        "message": ""

      }

    ]

  }

}

Response Code

200

Response Headers

{

  "Content-Type": "application/json"

}

---

Using cURL with the REST API

To create a VLAN, use the vREST API:

$ curl -u network-admin:pluribus_password -H "Content-Type:application/json" -X POST http://switch1/vRest/vlans -d '{"scope": "local","id": 1111,"description": "hello world"}'

 

A successful execution of the above cURL command returns the result:

{"result":{"status":"Success","result":[{"api.switch-name":"local","scope":"local","status":"Success","code":0,"message":"Vlans 1111 created"}]}}

By default, the vRest APIs provide fabric level information. To specifically access the resources of the switch (scope : local ), the switch ID needs to be specified in the URL. For switch ID specific information, use the command:

 

$ curl -u network-admin:pluribus_password http://switch1/vRest/vlans?api.switch={hostid} | python -m json.tool

 

as in the following example:

 

$ curl -u network-admin:pluribus_password http://10.110.0.48/vRest/vlans?api.switch=201327131 | python -m json.tool

For switch information listing a local scope:

$ curl -u network-admin:pluribus_password http://switch1/vRest/vlans?api.switch=fabric | python -m json.tool

or

$ curl -u network-admin:pluribus_password  http://switch1/vRest/vlans | python -m json.tool

 

as in the following example:

$ curl -u network-admin:pluribus_password  http://10.110.0.48/vRest/vlans | python -m json.tool

---

Note: Results returned may be an array.

---