Using SCI API Explorer

After you log in to the SCI User Interface, you can access the SCI API Explorer to generate reports by using a variety of APIs that SCI supports.

This section provides steps on how to enter the SCI API Explorer to log in, after which the following tasks are shown:
  1. Enter https://<your SCI IP address>/explorer in your web browser.
  2. Log in using the following default credentials:
    Username: admin
    Password: password
    Note: If you have changed the default password, please use the new password accordingly.
    The following screen appears:
    Figure 1. Ruckus Smart Analytics Screen when Entering API Explorer

    This screen exposes all the APIs from the SCI core engine.

Generating the Access Token

Before you can access all the APIs, you need to generate an access token.

Follow the steps below to generate the API access token:

  1. Click User on the screen shown above.
    The screen expands as follows:
    Figure 2. Clicking User
  2. Click on POST /users/login on the screen shown above.
  3. In the credentials section, enter the user credentials you used to log into the user interface, which, by default, are:
    Username: admin
    Password: password
    Input the string in the format {"username":"admin", "password":"password"} as shown below:
    Figure 3. Credentials


  4. Click the Try it out! tab in the Credentials section.
    The access code you need is generated in the Response body of the curl script, as displayed below:
    Figure 4. Access Token


  5. Copy this access token (without the quotation marks) and paste it in the Set Access Token field displayed at the top of the SCI user interface.
  6. Click Set Access Token.
    If successful, the "Token Set" string displays to the left of the space where you pasted in the token:
    Figure 5. Token Set


    Note: Now you can access all the API reports in the system. You might not get the whole report in the Response Body if it is a large amount of data. You can access the reports by using:
    • A Request URL. Paste this URL in a web browser to access the reports.
    • A curl script to SSH on to your machine and direct those reports to a desired location.

Querying to Obtain Report IDs

Each report in the SCI user interface is associated with a unique Report ID in the API. Each report consequently contains unique section IDs for each section within a report. This will also be shown in the following examples.

Follow the steps below to determine the list of IDs for each report.

  1. Click Report on the Ruckus Smart Analytics screen.
    You should then get a display that includes the following:
    Figure 6. Display after clicking on Report
  2. Click GET/reports.
    You should then get a display such as the following:
    Figure 7. GET/reports Response
  3. Click Try it out!
    Check the output in the Response Body. The following is a portion of that output:
    [
      {
        "title": "Clients Report",
        "urlSegmentName": "clients",
        "filterDataSource": "binnedSessions",
        "excludedFilters": null,
        "layout": [
          {
            "desiredWidth": "full",
            "layout": [
              {
                "section": 12,
                "desiredWidth": "half"
              },
              {
                "section": 13,
                "desiredWidth": "half"
              }
            ]
          },
          {
            "desiredWidth": "full",
            "section": 14
          },
          {
            "desiredWidth": "full",
            "section": 15
          },
          {
            "desiredWidth": "full",
            "section": 16
          }
        ],
        "headers": [
          "reportFilter",
          "periodButton",
          "savedFilters",
          "downloadButton"
        ],
        "routeParameters": null,
        "id": 1,
        "facetId": null
      },
    

    The code block shown above is for the "Clients Report," as you can see by the title in the first line of the code block. The Report ID is 1, which you can see near the end of the code block. The ID is always shown at the end of the corresponding report. Similarly, you can scroll through the output in the Response Body to obtain all the report IDs. For example, you will find that "Network Report" is ID 2.

Querying to Obtain Section IDs of a Specific Report

Each report in SCI contains multiple sections. Once you know the report IDs, you can obtain the names of each section within a report and their corresponding, unique section IDs.

Follow these steps to obtain the section titles and corresponding section IDs for all sections in a given report.

  1. Once you know the ID of the report you want, click GET/reports/{id}/sections.
    The following is displayed.
    Figure 8. Display from clicking GET/reports/{id}/sections
  2. Enter the Report ID in the "id" field. For example, for the Clients Report, enter an ID of 1.
  3. Click Try it out!
    A portion of the Response Body output is shown below:
    [
      {
        "title": "Overview",
        "queryName": "overview",
        "component": "ReportOverview",
        "defaultParameters": {
          "granularity": "all"
        },
        "layout": {
          "width": "half",
          "widgetTheme": "blue"
        },
        "url": null,
        "id": 12
      },
      {
        "title": "Top 10 Unique Clients by Traffic",
        "queryName": "topChart",
        "component": "BarChart",
        "defaultParameters": {
          "granularity": "all",
          "metric": "traffic"
        },
        "layout": {
          "width": "half",
          "headers": [
            {
              "component": "SelectFilter",
              "name": "metric",
              "options": {
                "traffic": "User Traffic",
                "rxBytes": "Rx User",
                "txBytes": "Tx User"
              }
            }
          ],
          "format": "bytesFormat",
          "colors": [
            "#5BA1E0",
            "#5BA1E0",
            "#5BA1E0",
            "#76CEF5",
            "#76CEF5",
            "#76CEF5",
            "#D9E6F5",
            "#D9E6F5",
            "#D9E6F5",
            "#D9E6F5"
          ],
          "drillDownRoute": "/report/client/${x}"
        },
        "url": null,
        "id": 13
      },

    The code block shown above is for the sections of the "Clients Report." The first segment of the Response Body above shows the title of "Overview." If you scroll down to the end of that segment, you see that the ID for that section is 12. The ID of a section is always shown at the end of the corresponding segment for the section. The ID for the next section shown above, "Top 10 Unique Clients by Traffic", is 13. You can scroll through the output in the Response Body to obtain all the section IDs for the report you have identified.

Querying the Data Endpoint

Once you know the Report ID and the Section ID you are interested in, you can query for specific data.

Follow these steps to query for specific data based on the Report ID and Section IDs.

  1. Click POST/reports/{id}/sections/{sectionId}/data.
    The following parameters are displayed.
    Figure 9. Display from clicking POST/reports/{id}/sections/{sectionId}/data
  2. Fill out the required fields, using the Report ID and Section ID that you have already determined from the previous queries described above.
    To determine if the metric parameter is required, look at the Response Body from for the section you are interested in, and check if "metric" is found under "defaultParameters". If it is, enter one of the values listed under "options." The figure below illustrates this scenario.
    Figure 10. Response Body that indicates a Metric is required
  3. You can also use the optional parameters. An example would be filtering on an AP MAC address of: 00:AA:BB:CC:44:D0. To do this, you would enter this exact string shown below into the filter field in the screen above: {"type":"or", "fields":[{"type":"selector", "dimension":"apMac", "value":"00:AA:BB:CC:44:D0"}]}
    If you want to generate a report using this filter, the Report ID of 1 (Clients Report), Section ID 12 (Overview section of Clients Report), and a time interval of your choice, the parameters once you have entered the information would appear as follows:
    Figure 11. Parameter Example for Querying Data on a Specific Section ID
    Other values you can use for dimensions in the "filter" string are shown below:
    Table 1. Dimensions to use in filter string parameter
    Dimension portion of filter string Value to use for Dimension
    System Name "system"
    Controller MAC "ctrlMac"
    Controller Name "ctrlName"
    Controller Serial "ctrlSerial"
    Zone "zoneName"
    AP Group "apGroup"
    AP MAC "apMAC"
    AP Name "apName"
    AP Serial "apSerial"
    SSID "ssid"
    Radio "radio"
    Session Type "sessionType"
  4. Click Try it out!.
    The data output is displayed in the Response Body.

Logging in to API Explorer Programmatically

You can log in using the curl command for POST /users/login. Ensure you use the –k option in the curl command.

The response to the call will contain a token that you can use in subsequent calls.

In subsequent calls, you can pass this token as a header “Authorization:<token>”.

The following example shows how to query section 28 for report ID 7 programmatically using the curl command.
curl -k -X POST --header "Content-Type: application/x-www-form-urlencoded" --header “Authorization: <your-auth-token>” --header "Accept:
application/json" -d "start=2016-12-13T20%3A30%3A46%2B00%3A00&end=2016-12-13T20%3A45%3A46%2B00%3A00" "https://<your-SCI-I
P>/api/reports/7/sections/28/data"