HTTP server
This is a little tool to serve the a YAML or JSON (or TOML, XML, INI) file as a mini API.
Requires twisted
to work
If Rickle
is not installed with net
extras the serve tool will not appear.
Prints the following options:
optional arguments:
-h, --help show this help message and exit
--input input file to serve
--host host address (default = localhost)
--port port number (default = 8080)
--private-key private key file path
--certificate ssl certificate file path
--auth basic auth (username:password)
--load-lambda load lambda true
--unsafe load UnsafeRickle (VERY UNSAFE)
--browser, -b open browser
--serialised, -s serve as serialised data (default = false)
Default output
The default output type is set to JSON
.
RICKLE_PATH_SEP
override
The /
overrides RICKLE_PATH_SEP
as the path separator.
Example
Take the following example:
If running the serve tool with the option -b
a new tab in the browser will be opened, directed to the listening port:
Port number
A port number can be defined specified using --port
:
Using the given example input file the following JSON data will be returned:
{
"root": {
"env_var": "do",
"heavens_gate": ".......",
"data": {
"dict_type": {
"a": 1,
"b": 2,
"c": 3
},
"list_type": [
"hello",
"world"
]
}
}
}
Note
The text for heavens_gate
is excluded for space (and your sanity).
Calling http://localhost:3301/root/random_joke
will return (example):
{
"type": "general",
"setup": "What kind of award did the dentist receive?",
"punchline": "A little plaque.",
"id": 255
}
And finally, if the given YAML or JSON file needs to be given in serialised form, use -s
:
which will give the following:
{
"root": {
"env_var": {
"type": "env",
"load": "USERNAME",
"default": "noname"
},
"encoded": {
"type": "base64",
"load": "dG9vIG1hbnkgc2VjcmV0cw=="
},
"heavens_gate": {
"type": "html_page",
"url": "https://www.heavensgate.com/",
"headers": null,
"params": null,
"expected_http_status": 200,
"hot_load": false
},
"random_joke": {
"type": "api_json",
"url": "https://official-joke-api.appspot.com/random_joke",
"http_verb": "GET",
"headers": null,
"params": null,
"body": null,
"deep": true,
"load_lambda": false,
"expected_http_status": 200,
"hot_load": true
},
"data": {
"dict_type": {
"a": 1,
"b": 2,
"c": 3
},
"list_type": [
"hello",
"world"
]
}
}
}
Output can also be given as application/yaml
with YAML output using the --output-type
option:
Which will produce the YAML output:
root:
data:
dict_type:
a: 1
b: 2
c: 3
list_type:
- hello
- world
env_var: do
heavens_gate: "......."
YAML mime types
In some browsers, the YAML output will be downloaded as data and not rendered in the browser.
PUT
new data
New data can be put using a path and any input data of type YAML, JSON, TOML, or XML.
Then running curl
with PUT
:
This will create at the new document path /root/new_path
an object any_data:3.14
.
Of course this means that the value 3.14
exists at /root/new_path/any_data
as the input data is read and is accessible as:
Furthermore, YAML, TOML, XML, INI, and ENV inputs are support:
curl -X PUT http://localhost:8080/root/new_ini < path/to/file.ini
curl -X PUT http://localhost:8080/root/new_toml < other/to/file.xml
Set X-rickle-output-type
header
The output type can be set with each GET
request. Say for example you want the output in TOML:
Will respond with TOML.
SSL and Auth
SSL can be used:
Basic auth
Basic auth can be added by using the --auth
flag with input username:password
or filename (YAML, JSON etc.).
For example:
And then used:
Or just using a single username combination:
Unsafe usage
Danger
Loading unknown code can be potentially dangerous. Only load files that you are fully aware what the Python code will do once executed. In general, a safe rule of thumb should be: don't load any Python code.
To enabled functions, the environment variable RICKLE_UNSAFE_LOAD
has to be set, and --load-lambda
and --unsafe
passed. Using the get-area.yaml
example again:
get-area.yaml | |
---|---|
Then the endpoint can be called: