Add README

esp8266example/README.md

@@ -0,0 +1,169 @@
+# ESP8266 Firewall with API
+
+## Example
+
+Clone this repository and open the folder `example` in Visual Studio Code.
+
+### Credentials
+
+After git is finished, add the WiFi credentials, username and password for basic auth by creating a `theSecrets.h` file based on the example that can be found in the `include` folder.
+
+### Compile and upload
+
+Finally compile and upload with the [official platformIO plugin](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide)
+
+## API
+
+Following endpoints can be used with the firewall (see `https://<IP_OF_ESP8266>:8080/api`):
+
+```json
+[
+  {
+    "endpoint": "https://10.93.0.246:8080/api/firewall/rules",
+    "description": "Get all Firewall Rules",
+    "method": "GET"
+  },
+  {
+    "endpoint": "https://10.93.0.246:8080/api/firewall/rules/<key>",
+    "description": "Get Firewall Rule by key",
+    "method": "GET"
+  },
+  {
+    "endpoint": "https://10.93.0.246:8080/api/firewall/rules",
+    "description": "Create Firewall Rule",
+    "method": "POST"
+  },
+  {
+    "endpoint": "https://10.93.0.246:8080/api/firewall/rules/<key>",
+    "description": "Update Firewall Rule by key",
+    "method": "PUT"
+  },
+  {
+    "endpoint": "https://10.93.0.246:8080/api/firewall/rules/<key>",
+    "description": "Delete Firewall Rule by key",
+    "method": "DELETE"
+  }
+]
+```
+
+Endpoints that show the rules and that can modify the rules are protected by basic auth. Username and password need to be set as described [here](https://github.com/flohoss/esp8266_firewall_api#credentials).
+
+### Get rules
+
+```sh
+curl -u username:password \
+https://10.93.0.246:8080/api/firewall/rules
+```
+
+```json
+// HTTP/1.1 200 OK
+// Content-Type: application/json; charset=utf-8
+// Content-Length: 109
+// Connection: keep-alive
+// Keep-Alive: timeout=2000
+[
+  {
+    "key": "1",
+    "ip": "10.93.0.211",
+    "port_from": "8080",
+    "port_to": "8080",
+    "protocol": "TCP",
+    "target": "ACCEPT"
+  }
+]
+```
+
+### Get rule
+
+```sh
+curl -u username:password \
+https://10.93.0.246:8080/api/firewall/rules/1
+```
+
+```json
+// HTTP/1.1 200 OK
+// Content-Type: application/json; charset=utf-8
+// Content-Length: 107
+// Connection: keep-alive
+// Keep-Alive: timeout=2000
+{
+  "key": "1",
+  "ip": "10.93.0.211",
+  "port_from": "8080",
+  "port_to": "8080",
+  "protocol": "TCP",
+  "target": "ACCEPT"
+}
+```
+
+### Create rule
+
+```sh
+curl -X POST -u username:password \
+https://10.93.0.246:8080/api/firewall/rules?ip=10.93.0.200&port_from=10&port_to=50&protocol=UDP&target=ACCEPT
+```
+
+```json
+// HTTP/1.1 201 Created
+// Content-Type: application/json; charset=utf-8
+// Content-Length: 104
+// Connection: keep-alive
+// Keep-Alive: timeout=2000
+{
+  "key": "2",
+  "ip": "10.93.0.200",
+  "port_from": "10",
+  "port_to": "50",
+  "protocol": "UDP",
+  "target": "ACCEPT"
+}
+```
+
+Available protocols are TCP, UDP & ALL
+
+Available targets are ACCEPT & DROP
+
+### Update rule
+
+```sh
+curl -X PUT -u username:password \
+https://10.93.0.246:8080/api/firewall/rules/2?ip=10.93.0.100&port_from=20&port_to=100&protocol=ALL&target=DROP
+```
+
+```json
+// HTTP/1.1 200 OK
+// Content-Type: application/json; charset=utf-8
+// Content-Length: 103
+// Connection: keep-alive
+// Keep-Alive: timeout=2000
+{
+  "key": "2",
+  "ip": "10.93.0.100",
+  "port_from": "20",
+  "port_to": "100",
+  "protocol": "ALL",
+  "target": "DROP"
+}
+```
+
+Available protocols are TCP, UDP & ALL
+
+Available targets are ACCEPT & DROP
+
+### Delete rule
+
+```sh
+curl -X DELETE -u username:password \
+https://10.93.0.246:8080/api/firewall/rules/2
+```
+
+```json
+// HTTP/1.1 200 OK
+// Content-Type: application/json; charset=utf-8
+// Content-Length: 36
+// Connection: keep-alive
+// Keep-Alive: timeout=2000
+{
+  "message": "firewall rule deleted"
+}
+```