EdgeOSAPI

An unofficial API wrapper in NodeJS for the Ubiquiti EdgeOS devices v1.x.x.

Notes

Tested on a EdgeRouter X v1.10.7. I'm assuming this is only compatible on the v1.x.x firmware only.

You may want to do a dry-run with an API client like PostMan on the endpoint /api/edge/get.json. After logging-in with a cookie session to view all the object properties.

Logging in on the root directory with a POST request with an x-www-form-urlencoded body with username and password key pair. Reuse the cookies for the subsequent requests. If you don't get 3 cookies (That I'm aware of) you may need to manually handle the initial redirects to the dashboard.

Protected requests (anything that changes the device) requires adding a X-CSRF-TOKEN to the headers; obtained from the cookies after login. Cookies by default are only good for about 20 minutes. It renews with every successful request.

Most of the help was from Matthew1471 from their repo at https://github.com/matthew1471/EdgeOS-API/tree/master/Documentation. Thank you!

Features

I have changed some properties to make it easier to access. However, you will need to follow exactly (including case-sensitivity) how it's structured when setting, updating, and removing configurations. (See the /api/edge/get.json response) The request will still go through, but nothing will update. This is a limitation by Ubiquiti that cannot be worked around from what I know.

Enough methods are completed for the basic CRUD operations on most properties on the device. With most things requiring the use of batch set and delete endpoint and method EdgeOS.batchSetConfig() & EdgeOS.batchDeleteConfig()

As I push updates to this more methods will appear. There will be some properties missing here that are not accessible. It's around 90% coverage. I have not implemented anything related to the Unifi and UNMS stuff.

Installation

Use the package manager npm to install.

npm install @brickert/edgeosapi

Usage

import { EdgeOS } from '@brickert/edgeosapi`;

try {
   const edgeOS = new EdgeOS({
       cookie_session_lifetime = 10,
       hostName = "example.local",
       username = "admin",
       password = "password",
       userAgent = "EdgeOSAPI"
   });

   await edgeOS.retryableLogin(3);
   
   await edgeOS.firewall.fetch();
   
   console.log(edgeOS.firewall.groups.network_groups.filter(group => group.name == "LAN"));
   /*   {
            name: "LAN",
            address: ["192.168.1.0/24"],
            description: "Example comment"
        }
    */
} catch (e) {
   throw e;
}