updated docs and cleaned up api somewhat

This commit is contained in:
Kevin Froman 2019-04-12 12:14:16 -05:00
parent 7c4e8bfa73
commit 3bea32a911
4 changed files with 71 additions and 38 deletions

View File

@ -56,6 +56,13 @@ Friend/contact manager
Encrypted, metadata-masking mail application. Perhaps the first distributed mail system to have basic forward secrecy.
# Documentation
More docs coming soon.
* [Block specification](docs/specs/block-spec.md)
* [HTTP API](docs/http-api.md)
# Install and Run on Linux
The following applies to Ubuntu Bionic. Other distros may have different package or command names.

View File

@ -1,7 +1,5 @@
# Onionr HTTP API
# About HTTP API
All HTTP interfaces in the Onionr reference client use the [Flask](http://flask.pocoo.org/) web framework with the [gevent](http://www.gevent.org/) WSGI server.
## Client & Public difference
@ -14,10 +12,66 @@ The public API server is available only remotely from Tor & I2P. It is the inter
Please note: endpoints that simply provide static web app files are not documented here.
(Client API docs coming soon)
* /serviceactive/pubkey
- Methods: GET
- Returns true or false based on if a given public key has an active direct connection service.
* /queueResponseAdd/key (DEPRECATED)
- Methods: POST
- Accepts form key 'data' to set queue response information from a plugin
- Returns success if no error occurs
* /queueResponse/key (DEPRECATED)
- Methods: GET
- Returns the queue response for a key. Returns failure with a 404 code if a code is not set.
* /ping
- Methods: GET
- Returns "pong!"
* /getblocksbytype/type
- Methods: GET
- Returns a list of stored blocks by a given type
* /getblockbody/hash
- Methods: GET
- Returns the main data section of a block
* /getblockdata/hash
- Methods: GET
- Returns the entire data contents of a block, including metadata.
* /getblockheader/hash
- Methods: GET
- Returns the header (metadata section) of a block.
* /lastconnect
- Methods: GET
- Returns the epoch timestamp of when the last incoming connection to the public API server was logged
* /site/hash
- Methods: GET
- Returns HTML content out of a block
* /waitforshare/hash
- Methods: POST
- Prevents the public API server from listing or sharing a block until it has been uploaded to at least 1 peer.
* /shutdown
- Methods: GET
- Shutdown Onionr. You should probably use /shutdownclean instead.
* /shutdownclean
- Methods: GET
- Tells the communicator daemon to shutdown Onionr. Slower but cleaner.
* /getstats
- Methods: GET
- Returns some JSON serialized statistics
* /getuptime
- Methods: GET
- Returns uptime in seconds
* /getActivePubkey
- Methods: GET
- Returns the current active public key in base32 format
* /getHumanReadable/pubkey
- Methods: GET
- Echos the specified public key in mnemonic format
* /insertblock
- Methods: POST
- Accepts JSON data for creating a new block. 'message' contains the block data, 'to' specifies the peer's public key to encrypt the data to, 'sign' is a boolean for signing the message.
# Public API
v0
* /
- Methods: GET
- Returns a basic HTML informational banner describing Onionr.

View File

@ -270,7 +270,6 @@ class API:
logger.info('Running api on %s:%s' % (self.host, self.bindPort))
self.httpServer = ''
self.pluginResponses = {} # Responses for plugin endpoints
self.queueResponse = {}
onionrInst.setClientAPIInst(self)
app.register_blueprint(friendsapi.friends)
@ -369,7 +368,10 @@ class API:
pass
else:
del self.queueResponse[name]
return Response(resp)
if resp == 'failure':
return resp, 404
else:
return resp
@app.route('/ping')
def ping():
@ -523,36 +525,6 @@ class API:
threading.Thread(target=self._core.insertBlock, args=(message,), kwargs={'header': bType, 'encryptType': encryptType, 'sign':sign, 'asymPeer': to, 'meta': meta}).start()
return Response('success')
@app.route('/apipoints/<path:subpath>', methods=['POST', 'GET'])
def pluginEndpoints(subpath=''):
'''Send data to plugins'''
# TODO have a variable for the plugin to set data to that we can use for the response
pluginResponseCode = str(uuid.uuid4())
resp = 'success'
responseTimeout = 20
startTime = self._core._utils.getEpoch()
postData = {}
if request.method == 'POST':
postData = request.form['postData']
if len(subpath) > 1:
data = subpath.split('/')
if len(data) > 1:
plName = data[0]
events.event('pluginRequest', {'name': plName, 'path': subpath, 'pluginResponse': pluginResponseCode, 'postData': postData}, onionr=onionrInst)
while True:
try:
resp = self.pluginResponses[pluginResponseCode]
except KeyError:
time.sleep(0.2)
if self._core._utils.getEpoch() - startTime > responseTimeout:
abort(504)
break
else:
break
else:
abort(404)
return Response(resp)
self.httpServer = WSGIServer((self.host, bindPort), app, log=None, handler_class=FDSafeHandler)
self.httpServer.serve_forever()
@ -578,8 +550,8 @@ class API:
def getUptime(self):
while True:
try:
return self._utils.getEpoch - startTime
except AttributeError:
return self._utils.getEpoch() - self.startTime
except (AttributeError, NameError):
# Don't error on race condition with startup
pass

View File

@ -58,7 +58,7 @@
<div id='sendMessage' class='overlay'>
<div class='overlayContent'>
<label>Select friend: <select id='friendSelect'></select></label>
<form method='post' action='/apipoints/mail/send' id='sendForm' enctype="application/x-www-form-urlencoded">
<form method='post' action='' id='sendForm' enctype="application/x-www-form-urlencoded">
<span class='closeOverlay' overlay='sendMessage'></span>
To: <input id='draftID' type='text' name='to' placeholder='pubkey' required>
Subject: <input name='subject' id='draftSubject' maxlength=25 type='text' placeholder='message subject'>