View Source JSON API

Endpoints

Get access points

This request returns a list of known access points and their properties. Hidden access points are not returned.

Path: /api/v1/access_points

Method: GET

Response: Array AccessPoint

Response Code: 200

Response

[
  {
    "ssid": "Free WiFi!",
    "frequency": 2437,
    "band": "wifi_2_4_ghz",
    "channel": 6,
    "flags": ["ess"],
    "signal_percent": 100,

  },
  {
    "ssid": "Imperial Star Destroyer",
    "frequency": 5755,
    "band": "wifi_5_ghz",
    "channel": 151,
    "flags": ["wpa2_psk_ccmp", "ess"],
    "signal_percent": 75
  }
]

Configure SSID priority

This endpoint takes a list of SSIDs. Each SSID is tried in order until a successful connection is made. It is not required to list all configured SSIDs.

Path: /api/v1/ssids

Method: PUT

Request: Array String

Response: Empty

Response Code: 204

Example

Request

[
  "Millennium Falcon",
  "Death Star",
  "TIE-fighter-01",
  "lukes-lightsaber"
]

Configure an SSID

Set connection parameters for an SSID.

Path: /api/v1/<ssid>/configuration

Method: PUT

Request: WiFiConfiguration

Response: Empty

Response Code: 204

Example

Request

/api/v1/millennium-falcon/configuration

{
  "key_mgmt": "wpa_psk",
  "password": "Chewbacca"
}

Errors

If the configuration is passed is invalid the endpoint will return with a 400 status with one of the below errors:

{
  "error": "password_required",
  "message": "A password is required for wpa_psk access points."
}

If the configuration is provide a key_mgmt field and there is no provided password.

{
 "error": "password_too_short",
 "message": "The minimum length for a password is 8."
}

If the password is less than 8 characters long as outlined in the IEEE Std 802.11i-2004 specification.

{
  "error": "invalid_characters",
  "message": "The password provided has invalid characters."
}

If the password contains characters that are not valid ASCII.

{
  "error": "password_too_long",
  "message": "The maximum length for a password is 63."
}

If the password is greater than 63 characters long as outlined in the IEEE Std 802.11i-2004 specification.

Delete an SSID configuration

Delete the configuration attached to an SSID

Path: /api/v1/<ssid>/configuration

Method: DELETE

Request: Empty

Response: Empty

Response Code: 200

Get configurations

Get the current known configurations.

Path: /api/v1/configurations

Method: GET

Request: Empty

Response: Array WiFiConfiguration - Passwords are filtered

Response Code: 200

Request

[
  {
    "ssid": "Millennium Falcon",
    "key_mgmt": "wpa_psk"
  }
]

Get configuration status

Get the current status of the configuration. This is useful after using the /api/v1/apply endpoint to figure out if the configurations that were provided work or not.

Path: /api/v1/configuration/status

Method: GET

Request: Empty

Response: ConfigurationStatus

Response Code: 200

Apply

A POST to this endpoint applies the configuration and attempts to connect to the configured WiFi networks. This will return back to AP mode and you can use the /api/v1/configuration/status endpoint to get whether or not the configuration worked or not.

Path: /api/v1/apply

Method: POST

Request: Empty

Response: Empty

Response Code: 202

Complete the configuration process

Finalize the configuration process. This will apply the configuration and not return to AP mode.

Path: /api/v1/complete

Method: GET

Request: Empty

Response: Empty

Response Code: 202

Types

AccessPoint 

{
  "ssid": String,
  "signal_percent": 0..100,
  "frequency": Integer,
  "band": Band,
  "channel": Integer,
  "flags": Flags
}

Band

This is the WiFi radio band that the access point is using.

"wifi_2_4_ghz"
"wifi_5_ghz"
"unknown"

Flags

Flags are reported by access points. They can be used to know whether a password is required to join the network. Example flags are "wpa2", "psk", and "eap". Flags are documented in the vintage_net_wifi documentation

KeyManagement

Key management is an interpretation of the Flags that determines what information that the user needs to provide to connect to the access point. For hidden access points where the Flags are unavailable, the user will need to pick one of these.

"none" - No security
"wpa_psk" - WPA or WPA2 with a pre-shared key
"wpa_eap" - WPA or WPA2 with a username and password

WiFiConfiguration

This specifies how to connect to one WiFi access point. The ssid and key_mgmt fields are required. Depending on the key_mgmt, password may be needed.

{
  "ssid": String,
  "key_mgmt": KeyManagement,
  "password": Optional String
}

ConfigurationStatus 

not_configured - No configuration attempts have taken place
good - A configuration was applied and is working
bad - A configuration was applied and is not working