documentation

Author: DevAlone

README.md

@@ -37,16 +37,20 @@ proxy_py has server based on aiohttp which is listening 127.0.0.1:55555(you can
 {
 	'model': 'proxy',
 	'method': 'get',
+	'order_by': 'response_time, uptime'
 }
 ```
 
+Note: order_by makes result sorting by one or more fields separated by comma.
+You can skip it. The required fields are model and method.
+
 It will return json response like this:
 
 ```
 {
 	'status': 'ok',
 	'count': 1,
-	'last_page': True,
+	'has_more': True,
 	'data': [{
 			"address": "http://127.0.0.1:8080",
 			"auth_data": null,
@@ -57,19 +61,19 @@ It will return json response like this:
 			"port": 8080,
 			"protocol": "http",
 			"uptime": 1509460949,
-			"white_ip_v4": null,
-			"white_ip_v6": null,
 		}
 	]
 }
 ```
 
+Note: All fields except *protocol*, *domain*, *port*, *auth_data*, *checking_period* and *address* can be null  
+
 Or error if something went wrong:
 
 ```
 {
 	'status': 'error',
-	'error': 'You should specify model',
+	'error_message': 'You should specify model',
 }
 ```
 
@@ -124,6 +128,10 @@ async def get_proxies():
     return result
 ```
 
+## API
+
+More about API read [here](https://github.com/DevAlone/proxy_py/tree/master/docs/API.md)
+
 ## How to deploy on production using supervisor, nginx and postgresql in 8 steps?
 
 1 Install supervisor, nginx and postgresql

docs/API.md

@@ -0,0 +1,123 @@
+# proxy_py API
+
+proxy_py expects HTTP POST requests with JSON as a body, so you need 
+to add header `Content-Type: application/json` and send correct
+JSON document.
+
+Example of correct request:
+```json
+{
+  "model": "proxy",
+  "method": "get"
+}
+```
+
+## Possible keys
+
+* `model` - specifies what you will work with. 
+Now it's only supported to work with `proxy` model.
+* `method` - what you're gonna do with it
+  * `get` - get model items as json objects. 
+  Detailed description is below
+  * `count` - count how many items there are.
+  Detailed description is below
+ 
+ 
+### get method
+
+`get` method supports following keys:
+* `order_by` (string) - specifies ordering fields as comma separated
+value.
+
+Examples:
+
+`"uptime"` just sorts proxies by uptime field ascending.
+
+Note: `uptime` is the timestamp from which proxy is working,
+NOT proxy's working time
+
+To sort descending use `-` before field name.
+
+`"-response_time"` returns proxies with maximum response_time first
+(in microseconds)
+
+It's possible to sort using multiple fields
+
+`"number_of_bad_checks, response_time"` returns proxies with minimum
+`number_of_bad_checks` first, if there are proxies with the same
+`number_of_bad_checks`, sorts them by `response_time`
+
+* `limit` (integer) -  specifying how many proxies to return
+* `offset` (integer) - specifying how many proxies to skip
+
+Example of `get` request:
+```json
+
+{
+    "model": "proxy",
+    "method": "get",
+    "order_by": "number_of_bad_checks, response_time",
+    "limit": 100,
+    "offset": 200
+}
+```
+
+Response
+ 
+```json
+{
+    "count": 6569,
+    "data": [
+        {
+            "address": "socks5://localhost:9999",
+            "auth_data": "",
+            "bad_proxy": false,
+            "domain": "localhost",
+            "last_check_time": 1517089048,
+            "number_of_bad_checks": 0,
+            "port": 9999,
+            "protocol": "socks5",
+            "response_time": 1819186,
+            "uptime": 1517072132
+        },
+
+        ...
+
+    ],
+    "has_more": true,
+    "status": "ok"
+}
+```
+ 
+* `count` (integer) - total number of proxies for that request
+* `data` (array) - list of proxies
+* `has_more` (boolean) - value indicating whether you can increase
+offset to get more proxies or not
+* `status` (string) - "error" if error happened, "ok" otherwise
+
+Example of error:
+
+Request:
+
+```json
+{
+    "model": "user",
+    "method": "get",
+    "order_by": "number_of_bad_checks, response_time",
+    "limit": 100,
+    "offset": 200
+}
+```
+
+Response:
+
+```json
+{
+    "error_message": ""Model \"user\" doesn't exist or isn't allowed",
+    "status": "error"
+}
+```
+
+### count method
+
+Same as get, but not returns data

models.py

@@ -28,8 +28,8 @@ class Proxy(Base):
     port = Column(Integer, nullable=False)
     auth_data = Column(String(64), default="", nullable=False)
 
-    last_check_time = Column(Integer, default=0)
     checking_period = Column(Integer, default=settings.MIN_PROXY_CHECKING_PERIOD, nullable=False)
+    last_check_time = Column(Integer, default=0)
     number_of_bad_checks = Column(Integer, default=0)
     uptime = Column(Integer, nullable=True, default=None)
     bad_uptime = Column(Integer, nullable=True, default=None)

server/requests_to_models/request_parser.py

@@ -96,7 +96,7 @@ def parse_dict(self, req_dict):
             raise ParseError('You should specify "model"')
 
         if req_dict['model'] not in self.config:
-            raise ParseError("Model doesn't exist or isn't allowed")
+            raise ParseError("Model \"{}\" doesn't exist or isn't allowed".format(req_dict['model']))
 
         config = self.config[req_dict['model']]