From d403f490e9f1b76fb04f026e3218f4cfd378c81a Mon Sep 17 00:00:00 2001 From: Kevin Froman Date: Fri, 12 Apr 2019 12:14:16 -0500 Subject: [PATCH] updated docs and cleaned up api somewhat --- README.md | 7 +++ docs/http-api.md | 60 ++++++++++++++++++++++++-- onionr/api.py | 40 +++-------------- onionr/static-data/www/mail/index.html | 2 +- 4 files changed, 71 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 58dac596..b63fe020 100755 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/http-api.md b/docs/http-api.md index b2fae877..d2ee56a5 100755 --- a/docs/http-api.md +++ b/docs/http-api.md @@ -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. diff --git a/onionr/api.py b/onionr/api.py index df8b09f2..ae6368e2 100755 --- a/onionr/api.py +++ b/onionr/api.py @@ -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(): @@ -522,36 +524,6 @@ class API: pass 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/', 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 diff --git a/onionr/static-data/www/mail/index.html b/onionr/static-data/www/mail/index.html index f3f337bd..08441075 100644 --- a/onionr/static-data/www/mail/index.html +++ b/onionr/static-data/www/mail/index.html @@ -58,7 +58,7 @@
-
+ To: Subject: