API documentation

README.md

@@ -2,7 +2,7 @@
 
 Very simple API for managing local iptables chain: `APIBANLOCAL`
 
-Simple `GET` actions of add, remove, and flush.
+Simple `GET` actions of add, remove, and flush (see [API usage](#API-usage) for more).
 
 ## Usage
 
@@ -14,6 +14,10 @@ Defaults:
 * log: `/var/log/iptables-api.log`
 * target: `REJECT`
 
+Compiled `iptables-api` will work for most linux distributions and `iptables-api-arm` will work for most Raspberry Pi distributions.
+
+You can also compile the program using `go build iptables-api.go`.
+
 ### Example with flags
 
 `./iptables-api -log=stdout -port=8008 -target=DROP`
@@ -72,6 +76,117 @@ event_route[htable:expired:ipban] {
 }
 ```
 
+## API Usage
+
+### Add/Block IP
+
+Add an IP to iptables. iptables or ip6tables will be chosen based on the IP.
+
+* **URL**: `/addip/[ipaddress]` or `/blockip/[ipaddress]`
+* **METHOD**: `GET`
+* **Auth**: None
+* **RESPONSE**: 200/4xx/5xx
+
+#### Add/Block Success Examples
+
+* GET `/addip/1.2.3.4`  
+* RESPONSE `200 OK`
+
+```json
+{"success":"added"}
+```
+
+* GET `/blockip/2001:db8:3333:4444:5555:6666:7777:8888`
+* RESPONSE `200 OK`
+
+```json
+{"success":"added"}
+```
+
+#### Add/Block Error Examples
+
+* GET `/addip/1.2.3`
+* RESPONSE `400 Bad Request`
+
+```json
+{"error":"only valid ip addresses supported"}
+```
+
+* GET `/blockip/2001:db8:3333:4444:5555:6666:8888`
+* RESPONSE `400 Bad Request`
+
+```json
+{"error":"only valid ip addresses supported"}
+```
+
+### Remove/Unblock IP
+
+Remove an IP from iptables. iptables or ip6tables will be chosen based on the IP.
+
+* **URL**: `/removeip/[ipaddress]` or `/unblockip/[ipaddress]`
+* **METHOD**: `GET`
+* **Auth**: None
+* **RESPONSE**: 200/4xx/5xx
+
+#### Remove/Unblock Success Examples
+
+* GET `/removeip/1.2.3.4`  
+* RESPONSE `200 OK`
+
+```json
+{"success":"removed"}
+```
+
+* GET `/unblockip/2001:db8:3333:4444:5555:6666:7777:8888`
+* RESPONSE `200 OK`
+
+```json
+{"success":"removed"}
+```
+
+#### Remove/Unblock Error Examples
+
+* GET `/removeip/1.2.3`
+* RESPONSE `400 Bad Request`
+
+```json
+{"error":"only valid ip addresses supported"}
+```
+
+* GET `/unblockip/2001:db8:3333:4444:5555:6666:8888`
+* RESPONSE `400 Bad Request`
+
+```json
+{"error":"only valid ip addresses supported"}
+```
+
+### Flush APIBANLOCAL chain
+
+Flushes the iptables and ip6tables APIBANLOCAL chain.
+
+* **URL**: `/flushchain`
+* **METHOD**: `GET`
+* **Auth**: None
+* **RESPONSE**: 200/4xx/5xx
+
+#### Flush Success Example
+
+* GET `/flushchain`  
+* RESPONSE `200 OK`
+
+```json
+{"success":"flushed"}
+```
+
+#### Flush Error Example
+
+* GET `/flushchain`
+* RESPONSE `500 Internal Server Error`
+
+```json
+{"error":"error initializing iptables"}
+```
+
 ## License / Warranty
 
 iptables-api is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version