An unaspiring read-only HTTP API server written in Python 3.
Easily extended with your own commands.
Includes default commands for querying Wikipedia, Wikidata and the Magic 8-Ball.
Try the live demo: http://api.haykranen.nl
- Source on Github
- Written by Hay Kranen
To run the server simply run server.py in the root. There's also a uwsgi.ini configuration example for production use.
Another option is simply running this with an init / systemd script (see etc/ubuntu-init.conf for an example), and proxy the calls using something like Nginx. See etc/nginx-example.conf for an example.
For debugging purposes try running server.py with the debug=1 flag:
$ python server.py --debug=1
Or simply use -d
$ python server.py -d
To disable caching use the -nc flag.
This will run your Chantek server on port 5000.
For a list of all commands try going to http://localhost:5000/_commands.
All commands can be queried like this:
$ curl http://localhost:5000/<command>?param1=foo¶m2=bar
Commands with methods (see below) can be called like this:
$ curl http://localhost:5000/<command>/<method>?param1=foo¶m2=bar
Commands return their data as JSON following a consistent format:
$ curl http://localhost:5000/wikipedia/define?q=Chantek
{
// Contains the original parameters
"params": {
"q": "Chantek"
},
// Did an error occur during your call?
"error": false,
// Contains the original command
"command": "wikipedia",
// Response from the command
"response": {
"extract": "Chantek (born December 17, 1977, at the Yerkes Regional Primate Research Center in Atlanta, Georgia) is a male orangutan who has mastered the use of a number of intellectual skills, including sign language, taught by American anthropologists Lyn Miles and Ann Southcombe. In Malay and Indonesian, cantik (pronounced chanteek) means \"lovely\" or \"beautiful\".",
"ns": 0,
"pageid": 1577406,
"title": "Chantek"
},
// Version number
"chantek": "0.1.0"
}
HTTP responses by default are CORS enabled for use in web applications.
Commands go in the commands folder. Every command should be in a subfolder, with at least a __init__.py file (this should be empty) and a command.py file.
For example:
chantek/
commands/
mycommand/
__init__.py
command.py
otherlib.py
data.json
The simplest command.py file has a structure like this:
def run(args):
return "hello world"
args gives back all the url arguments given in the query as a dict.
To write a command with methods (like command/verb), write your command like this:
methods = ("foo")
def run(args, method):
if method == "bar":
return "Bar!"
A command can be known under several aliases:
# hello.py
aliases = ['hola']
def run(args):
return "hello world"
# This command can be reached under both 'hello' and 'hola'
To indicate that a command is cacheable simple write a constant in your command like this:
CACHEABLE = True
This will save every unique URL query to an configured cache.
You can make only some methods cacheable, to do so, simply use a tuple instead of a bool
methods = ("search", "random")
CACHEABLE = ("search") # 'random' should not be cacheable
Currently there are two caching options: in-memory (this simply saves stuff to a dict), or Redis. Optionally, an expire timeout can be given in seconds. See the config.py file for instructions on how to configure your cache.
I should probably make a requirements.txt file sometime, for now run this:
sudo pip install flask requests pyquery lxml redis xmltodict python-dateutil
Things that are not working yet and should be done:
- Commands should be self-documenting, and display help in the API
- Going to the root of the server (e.g.
http://localhost:5000) should return an interactive console - More commands!
"Api" pronounced in Dutch means "monkey", and Chantek is a very special monkey indeed. He's mastered sign language, and even understands spoken English. Given the fact that API's are all about communication, it made sense to name a HTTP server after a monkey that speaks English.