# JSON API
## Endpoints
* [Get Access Points](#get-access-points)
* [Configure SSID Priority](#configure-ssid-priority)
* [Configure an SSID](#configure-an-ssid)
* [Delete an SSID configuration](#delete-an-ssid-configuration)
* [Get Configurations](#get-configurations)
* [Get Configuration Status](#get-configuration-status)
* [Apply](#apply)
* [Complete the Configuration Process](#complete-the-configuration-process)
### 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
```json
[
{
"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
```json
[
"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`
```json
{
"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:
```json
{
"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.
```json
{
"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.
```json
{
"error": "invalid_characters",
"message": "The password provided has invalid characters."
}
```
If the password contains characters that are not valid ASCII.
```json
{
"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
```json
[
{
"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
```s
{
"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.
```s
"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](https://hexdocs.pm/vintage_net_wifi/VintageNetWiFi.AccessPoint.html)
### 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.
```s
"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.
```s
{
"ssid": String,
"key_mgmt": KeyManagement,
"password": Optional String
}
```
### ConfigurationStatus
```s
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
```