Version: 10.1

cURL Examples

cURL is a command line tool for interacting with many Web based resources. It is used here for the purposes of demonstrating rWeb features. Any library that supports cookies and the four HTTP verbs may be used.

warning

The examples here use cURL's -k / --insecure flag for ease of use. Setting up SSL validation is recommended in production.

API Key Based Authentication

Uses an API Key and the Authorization header to log in. This does not establish a session and the API key will need to be sent for each request.

Simple request for current user roles:

$ curl -H 'Authorization: token 903509033849c9d6a899ef9a64cb8795' \
       -H 'Accept: application/json' \
       -k \
       -w "\nHTTP_STATUS:%{http_code}\n" \
       https://rweb1/authentication

info

Starting in rWeb 9.2.0, you can use API Key based authentication instead of needing to create and store a cookie. The remaining examples on the page will show both methods of authentication.

The following is an example of a curl login to:

rWeb server hostname = rweb1
username = admin
password = admin123

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -c cookie.jar \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -k \
       -X POST \
       -d '{"data": {"login":"admin", "password":"admin123"}}' \
       https://rweb1/authentication

{
  "login": "admin",
  "roles": [
    {
      "name": "admin",
      "description": "",
      "features": [
        {
          "name": "device",
          "privilege": "rw"
        },
        {
          "name": "rweb",
          "privilege": "rw"
        },
        {
          "name": "mitigation_reporting",
          "privilege": "rw"
        },
        {
          "name": "mitigation_config",
          "privilege": "rw"
        },
        {
          "name": "limit_resource",
          "privilege": "rw"
        },
        {
          "name": "group_routing",
          "privilege": "rw"
        },
        {
          "name": "zone_routing",
          "privilege": "rw"
        },
        {
          "name": "group",
          "privilege": "rw"
        },
        {
          "name": "group_admin",
          "privilege": "rw"
        }
      ],
      "role_resource": "/roles/1",
      "users": [
        "admin",
        "upgrade"
      ],
      "admin_group": {
        "name": "Default",
        "description": "",
        "mode": "NONE",
        "customer_resource": "/customers/0",
        "zones_resource": "/groups/0/zones",
        "reports_resource": "/groups/0/report_statuses",
        "customer_configurations_resource": "/groups/0/configurations",
        "customer_devices_resource": "/groups/0/mapped_devices",
        "customer_traffic_resource": "/groups/0/traffic",
        "customer_logs_resource": "/groups/0/logs",
        "group_resource": "/groups/0",
        "group_configurations_resource": "/groups/0/configurations",
        "group_traffic_resource": "/groups/0/traffic",
        "group_logs_resource": "/groups/0/logs",
        "members_resource": "/groups/0/members",
        "roles_resource": "/groups/0/roles",
        "users_resource": "/groups/0/users",
        "templates_resource": "/groups/0/templates",
        "subnets_resource": "/groups/0/subnets",
        "mapped_devices_resource": "/groups/0/mapped_devices",
        "pre_mapped_devices_resource": "/groups/0/pre_mapped_devices",
        "sub_groups_resource": "/groups/0/groups",
        "parent_resource": ""
      },
      "group_resources": [
        "/groups/0",
        "/groups/1",
        "/groups/2",
        "/groups/3",
        "/groups/5"
      ]
    }
  ],
  "group": {
    "name": "Default",
    "description": "",
    "mode": "NONE",
    "customer_resource": "/customers/0",
    "zones_resource": "/groups/0/zones",
    "reports_resource": "/groups/0/report_statuses",
    "customer_configurations_resource": "/groups/0/configurations",
    "customer_devices_resource": "/groups/0/mapped_devices",
    "customer_traffic_resource": "/groups/0/traffic",
    "customer_logs_resource": "/groups/0/logs",
    "group_resource": "/groups/0",
    "group_configurations_resource": "/groups/0/configurations",
    "group_traffic_resource": "/groups/0/traffic",
    "group_logs_resource": "/groups/0/logs",
    "members_resource": "/groups/0/members",
    "roles_resource": "/groups/0/roles",
    "users_resource": "/groups/0/users",
    "templates_resource": "/groups/0/templates",
    "subnets_resource": "/groups/0/subnets",
    "mapped_devices_resource": "/groups/0/mapped_devices",
    "pre_mapped_devices_resource": "/groups/0/pre_mapped_devices",
    "sub_groups_resource": "/groups/0/groups",
    "parent_resource": ""
  },
  "user": "/users/0"
}
 
 HTTP_STATUS:201

Notes:

The option -k is added here to bypass SSL authentication. In real life application, we recommend that the proper SSL keys are exchanged and the -k option is not used.
The -w flag prints out the HTTP status code after the results of the HTTP query.
The -d flag provides the login name, password and account type to the server for processing.
The -c flag saves the authentication cookie to the file 'cookie.jar'. The cookie is required for accessing other resources in the API if not using an API token.
HTTP Status code 201 indicates that the command has executed successfully.
The JSON document indicates that the user 'admin' is part of the administrators group. This is a built-in group with the highest privilege level.

Listing Groups

Data in rWeb is organized around "Groups". Below is an example of how to access this group information.

Using Authentication Cookies

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -H "Accept:application/json" \
       -k \
       -b cookie.jar \
       https://rweb1/groups 

Using API Token

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -H "Accept:application/json" \
       -H "Authorization: token 6d776df80f7ef2eba4dfd0485c776642" \
       -k \
       https://rweb1/groups 

Result

 {
  "rows": 5,
  "data": [
    {
      "name": "Default",
      "description": "",
      "mode": "NONE",
      "customer_resource": "/customers/0",
      "zones_resource": "/groups/0/zones",
      "reports_resource": "/groups/0/report_statuses",
      "customer_configurations_resource": "/groups/0/configurations",
      "customer_devices_resource": "/groups/0/mapped_devices",
      "customer_traffic_resource": "/groups/0/traffic",
      "customer_logs_resource": "/groups/0/logs",
      "group_resource": "/groups/0",
      "group_configurations_resource": "/groups/0/configurations",
      "group_traffic_resource": "/groups/0/traffic",
      "group_logs_resource": "/groups/0/logs",
      "members_resource": "/groups/0/members",
      "roles_resource": "/groups/0/roles",
      "users_resource": "/groups/0/users",
      "templates_resource": "/groups/0/templates",
      "subnets_resource": "/groups/0/subnets",
      "mapped_devices_resource": "/groups/0/mapped_devices",
      "pre_mapped_devices_resource": "/groups/0/pre_mapped_devices",
      "sub_groups_resource": "/groups/0/groups",
      "parent_resource": ""
    },
    {
      "name": "king",
      "description": "",
      "mode": "NONE",
      "customer_resource": "/customers/1",
      "zones_resource": "/groups/1/zones",
      "reports_resource": "/groups/1/report_statuses",
      "customer_configurations_resource": "/groups/1/configurations",
      "customer_devices_resource": "/groups/1/mapped_devices",
      "customer_traffic_resource": "/groups/1/traffic",
      "customer_logs_resource": "/groups/1/logs",
      "group_resource": "/groups/1",
      "group_configurations_resource": "/groups/1/configurations",
      "group_traffic_resource": "/groups/1/traffic",
      "group_logs_resource": "/groups/1/logs",
      "members_resource": "/groups/1/members",
      "roles_resource": "/groups/1/roles",
      "users_resource": "/groups/1/users",
      "templates_resource": "/groups/1/templates",
      "subnets_resource": "/groups/1/subnets",
      "mapped_devices_resource": "/groups/1/mapped_devices",
      "pre_mapped_devices_resource": "/groups/1/pre_mapped_devices",
      "sub_groups_resource": "/groups/1/groups",
      "parent_resource": "/groups/0"
    },
    {
      "name": "Tier1",
      "description": "",
      "mode": "NONE",
      "customer_resource": "/customers/2",
      "zones_resource": "/groups/2/zones",
      "reports_resource": "/groups/2/report_statuses",
      "customer_configurations_resource": "/groups/2/configurations",
      "customer_devices_resource": "/groups/2/mapped_devices",
      "customer_traffic_resource": "/groups/2/traffic",
      "customer_logs_resource": "/groups/2/logs",
      "group_resource": "/groups/2",
      "group_configurations_resource": "/groups/2/configurations",
      "group_traffic_resource": "/groups/2/traffic",
      "group_logs_resource": "/groups/2/logs",
      "members_resource": "/groups/2/members",
      "roles_resource": "/groups/2/roles",
      "users_resource": "/groups/2/users",
      "templates_resource": "/groups/2/templates",
      "subnets_resource": "/groups/2/subnets",
      "mapped_devices_resource": "/groups/2/mapped_devices",
      "pre_mapped_devices_resource": "/groups/2/pre_mapped_devices",
      "sub_groups_resource": "/groups/2/groups",
      "parent_resource": "/groups/0"
    },
    {
      "name": "Tier2",
      "description": "",
      "mode": "NONE",
      "customer_resource": "/customers/3",
      "zones_resource": "/groups/3/zones",
      "reports_resource": "/groups/3/report_statuses",
      "customer_configurations_resource": "/groups/3/configurations",
      "customer_devices_resource": "/groups/3/mapped_devices",
      "customer_traffic_resource": "/groups/3/traffic",
      "customer_logs_resource": "/groups/3/logs",
      "group_resource": "/groups/3",
      "group_configurations_resource": "/groups/3/configurations",
      "group_traffic_resource": "/groups/3/traffic",
      "group_logs_resource": "/groups/3/logs",
      "members_resource": "/groups/3/members",
      "roles_resource": "/groups/3/roles",
      "users_resource": "/groups/3/users",
      "templates_resource": "/groups/3/templates",
      "subnets_resource": "/groups/3/subnets",
      "mapped_devices_resource": "/groups/3/mapped_devices",
      "pre_mapped_devices_resource": "/groups/3/pre_mapped_devices",
      "sub_groups_resource": "/groups/3/groups",
      "parent_resource": "/groups/2"
    },
    {
      "name": "Tier3a",
      "description": "",
      "mode": "NONE",
      "customer_resource": "/customers/5",
      "zones_resource": "/groups/5/zones",
      "reports_resource": "/groups/5/report_statuses",
      "customer_configurations_resource": "/groups/5/configurations",
      "customer_devices_resource": "/groups/5/mapped_devices",
      "customer_traffic_resource": "/groups/5/traffic",
      "customer_logs_resource": "/groups/5/logs",
      "group_resource": "/groups/5",
      "group_configurations_resource": "/groups/5/configurations",
      "group_traffic_resource": "/groups/5/traffic",
      "group_logs_resource": "/groups/5/logs",
      "members_resource": "/groups/5/members",
      "roles_resource": "/groups/5/roles",
      "users_resource": "/groups/5/users",
      "templates_resource": "/groups/5/templates",
      "subnets_resource": "/groups/5/subnets",
      "mapped_devices_resource": "/groups/5/mapped_devices",
      "pre_mapped_devices_resource": "/groups/5/pre_mapped_devices",
      "sub_groups_resource": "/groups/5/groups",
      "parent_resource": "/groups/3"
    }
  ],
  "start": 0
}
 
 HTTP_STATUS:200

Notes:

The -b flag sends the cookie generated during the authentication step.
Replace 6d776df80f7ef2eba4dfd0485c776642 with your unique token if using an API token.
The group URLs that are returned point to group resources which identify and hold additional information about each group.

Creating a Group Using POST

Using Authentication Cookies

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -k \
       -b cookie.jar \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -X POST \
       -d '{"data":{"name":"New Group","description":"Another new group"}}' \
       https://rweb1/groups

Using API Token

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -k \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Authorization: token 6d776df80f7ef2eba4dfd0485c776642" \
       -X POST \
       -d '{"data":{"name":"New Group","description":"Another new group"}}' \
       https://rweb1/groups

Result

{
  "name": "New Group",
  "description": "Another new group",
  "mode": "NONE",
  "customer_resource": "/customers/7",
  "zones_resource": "/groups/7/zones",
  "reports_resource": "/groups/7/report_statuses",
  "customer_configurations_resource": "/groups/7/configurations",
  "customer_devices_resource": "/groups/7/mapped_devices",
  "customer_traffic_resource": "/groups/7/traffic",
  "customer_logs_resource": "/groups/7/logs",
  "group_resource": "/groups/7",
  "group_configurations_resource": "/groups/7/configurations",
  "group_traffic_resource": "/groups/7/traffic",
  "group_logs_resource": "/groups/7/logs",
  "members_resource": "/groups/7/members",
  "roles_resource": "/groups/7/roles",
  "users_resource": "/groups/7/users",
  "templates_resource": "/groups/7/templates",
  "subnets_resource": "/groups/7/subnets",
  "mapped_devices_resource": "/groups/7/mapped_devices",
  "pre_mapped_devices_resource": "/groups/7/pre_mapped_devices",
  "sub_groups_resource": "/groups/7/groups",
  "parent_resource": "/groups/0"
}
 
 HTTP_STATUS:201

Notes:

The -b flag sends the cookie generated during the authentication step.
Replace 6d776df80f7ef2eba4dfd0485c776642 with your unique token if using an API token.
The -X POST flag sends an HTTP POST, used for creation of new resources.
The -d flag is followed by a JSON payload to send with the request. It requires a corresponding -H flag to define the type of the data.
Note that all properties that are sent as part of the JSON payload must be part of a JSON object called data.
The 201 status code indicates specifically that a resource has been created successfully.

Updating a Group Using PUT

Using Authentication Cookies

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -k \
       -b cookie.jar \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -X PUT \
       -d '{"data":{"name":"new_customer_name","description":"A changed description"}}' \
       https://rweb1/groups/7

Using API Token

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -k \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Authorization: token 6d776df80f7ef2eba4dfd0485c776642" \
       -X PUT \
       -d '{"data":{"name":"new_customer_name","description":"A changed description"}}' \
       https://rweb1/groups/7

Result

 {}
 
 HTTP_STATUS:200

Notes:

The -b flag sends the cookie generated during the authentication step.
Replace 6d776df80f7ef2eba4dfd0485c776642 with your unique token if using an API token.
Updates of existing resources are handled through an HTTP PUT.
A resource's path (/groups/7) will never change. That is the best way of uniquely identifying a resource. There may also be restrictions on the parameters of a resource.

Handling Errors

Using Authentication Cookies

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -k \
       -b cookie.jar \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -X DELETE \
       https://172.16.0.180/groups/0

Using API Token

$ curl -w "\nHTTP_STATUS:%{http_code}\n" \
       -k \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Authorization: token 6d776df80f7ef2eba4dfd0485c776642" \
       -X DELETE \
       https://172.16.0.180/groups/0

Result

{"detail":["Can not delete default group"]}

HTTP_STATUS:400

Note:

The -b flag sends the cookie generated during the authentication step.
Replace 6d776df80f7ef2eba4dfd0485c776642 with your unique token if using an API token.
This command attempts to delete the Default Group, which is the only group that must always exist and can not be removed.
An HTTP status code in the 4xx range indicates that the command has failed.
The JSON document attempts to clarify which field of the request caused a problem.
rWeb will attempt to report as many problems with the request as possible, so there may be multiple fields described in the response.

API Key Based Authentication​

Cookie Based Authentication​

Listing Groups​

Using Authentication Cookies​

Using API Token​

Result​

Creating a Group Using POST​

Using Authentication Cookies​

Using API Token​

Result​

Updating a Group Using PUT ​

Using Authentication Cookies​

Using API Token​

Result​

Handling Errors​

Using Authentication Cookies​

Using API Token​

Result​

API Key Based Authentication

Cookie Based Authentication

Listing Groups

Using Authentication Cookies

Using API Token

Result

Creating a Group Using POST

Using Authentication Cookies

Using API Token

Result

Updating a Group Using PUT

Using Authentication Cookies

Using API Token

Result

Handling Errors

Using Authentication Cookies

Using API Token

Result