search

Art-of-WiFi / UniFi-API-browser

Tool to browse data exposed by Ubiquiti's UniFi Controller API
MIT License
1.12k stars 151 forks source link
api api-client bootstrap browse-data controller curl php ubiquiti ubnt unifi

readme

UniFi API browser

This tool allows you to browse data exposed through the UniFi Controller API, developed using PHP, JavaScript, and the Bootstrap CSS framework. It comes bundled with a PHP class for access to the UniFi Controller API, which supports more API endpoints than the UniFi API browser tool.

If you plan on creating your own PHP code to interact with the UniFi controller API, it is recommended to use the standalone version of the API client class, which can be found at https://github.com/Art-of-WiFi/UniFi-API-client. There, you will also find examples and detailed instructions on how to use it.

Please keep the following in mind when using the UniFi API browser:

Upgrading from 1.x to 2.x

Because the structure of the configuration file has changed, we recommend creating a fresh install when upgrading from 1.x to 2.x.

Features

The UniFi API browser tool offers the following features:

Data collections/API endpoints currently implemented in the API browser

Please note that the bundled API client supports many more API endpoints, not all make sense to add to the API browser though.

Requirements

Installation

Installation of this tool is quite straightforward. The easiest way to do this is by using git clone which also allows for easy updates:

Alternatively, you may choose to download the zip file and unzip it in your directory of choice, then follow the configuration steps below.

Installation using Docker

@scyto maintains Docker containers for quick and easy deployment of the UniFi API browser tool. Please refer to this Wiki page within the repository for more details. Please note we don't provide support related to Docker-based installs.

Configuration

UniFi OS support

Support for UniFi OS-based controllers (for example, the UniFi Dream Machine Pro) has been added with version 2.0.7. When adding the details for a UniFi OS device to the config/config.php file, please make sure not to add a port suffix or trailing slashes to the URL.

When using the UniFi API browser to connect to a Network Application on a UniFi OS-based gateway via the WAN interface, it is necessary to create a specific firewall rule to allow external access to port 443 on the gateway's local interface. For more information, please refer to the following blog post for further details: https://artofwifi.net/2022/04/07/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro/

Extending the Collections dropdown menu

Since version 2.0.0 you can extend the Collections dropdown menu with your own options by adding them to the config.php file.

Here's an example:

/**
 * adding a custom sub-menu example
 */
$collections = array_merge($collections, [
    [
        'label' => 'Custom Menu', // length of this string is limited due to dropdown menu width
        'options' => [
            [
                'type' => 'collection', // either 'collection' or 'divider'
                'label' => 'hourly site stats past 24 hours', // string that is displayed in the dropdown menu
                'method' => 'stat_hourly_site', // name of the method/function in the API client class that is called
                'params' => [(time() - (24 * 60 *60)) * 1000, time() * 1000], // an array containing the parameters as they are passed to the method/function
            ],
            [
                'type' => 'collection',
                'label' => 'daily site stats past 31 days',
                'method' => 'stat_daily_site',
                'params' => [(time() - (31 * 24 * 60 *60)) * 1000, time() * 1000],
            ],
            [
                'type' => 'divider', // dividers have no other properties
            ],
            [
                'type' => 'collection',
                'label' => 'enable the site LEDs',
                'method' => 'site_leds', // don't go too wild when adding such calls, this example is simply to show the flexibility
                'params' => [true]
            ],
            [
                'type' => 'collection',
                'label' => 'disable the site LEDs',
                'method' => 'site_leds', // don't go too wild when adding such calls, this example is simply to show the flexibility
                'params' => [false]
            ],
        ],
    ],
]);

Note: for a collection type menu option the type, label, method, and params "properties" are required.

This is what the result looks like for the above example:

Custom sub menu

Updates

If you installed the tool using the git clone command, you can apply updates by going into the directory where the tool is installed, and running the git pull command from there.

Otherwise, you can simply copy the contents from the latest zip file to the directory where the tool has been installed.

Credits

The PHP API client that comes bundled with this tool is based on the work by the following developers:

and the API as published by Ubiquiti:

Other included libraries:

Security notice

[!CAUTION] It is important to note that the UniFi API browser tool is a powerful tool that allows access to sensitive data and configuration options on your UniFi controller. It is therefore important you take appropriate security measures, such as limiting access to the tool to trusted individuals. Additionally, you should be aware of the security risks associated with running PHP code on your server.

We highly recommend enabling the username/password authentication feature by creating a config/users.php based on the included config/users-template.php file. When creating passwords and their SHA512 hashes for entry in the config/users.php file, make sure to use strong random passwords. Please refer to the instructions in the config/users-template.php file for further details

Support and Feedback

This project is actively maintained, and feedback and suggestions are always welcome. If you encounter any issues or have any suggestions for improvements, please use the GitHub issue list or the Ubiquiti Community forums (https://community.ubnt.com/t5/UniFi-Wireless/UniFi-API-browser-tool-released/m-p/1392651) to share your ideas and questions.

Screenshots

Here are a couple of screenshots of the tool in action.

The Login form when user authentication is enabled:

Login form

The controller selection dropdown menu:

Controller selection

The site selection dropdown menu:

Site selection

The collection dropdown menu:

Select collection

Showing the site settings collection in JSON format:

Site settings in JSON format

Showing the site settings collection in interactive PHP format:

Site settings in PHP format

The "About" modal:

About modal