$ git clone https://thingshare.ion.nu/thingshare.git
commit c0edbabf3583590f89e0d366d288bd396a7bdfc8
Author: Alicia <...>
Date: Mon Nov 2 21:39:25 2020 +0100
RPC documentation.
diff --git a/docs/RPCs b/docs/RPCs
new file mode 100644
index 0000000..fdd7325
--- /dev/null
+++ b/docs/RPCs
@@ -0,0 +1,144 @@
+RPC documentation, for alternative implementations, scripting, compatibility checking, etc.
+Requests are made to https://<Domain>/rpc/<RPC>
+
+Signed RPC requests are sent as POST requests with the following fields:
+data: <String containing the JSON-encoded message>
+signature: <Base64-encoded signature of the data string>
+algorithm: <Algorithm used to generate the signature>
+Additionally signed requests must specify their origin node with the X-Thingshare-node HTTP header, for the recipient to look up the public key for signature verification (RPC: rpckey)
+
+RPC: thing/<ID>
+Returns information about the thing by the given ID on this node.
+Return format:
+{
+ "id": <ID>,
+ "name": <Name>,
+ "description": <Description, markdown>,
+ "date": <Date>,
+ "files": [
+ {
+ "name": <Filename>,
+ "path": <Path to file, not necessarily preserving the name>,
+ "preview": <Path to preview 2D image>,
+ "preview3d": <Path to preview 3D model in X3D format. Optional>,
+ "type": <MIME/Media type. Optional>
+ },
+ <More entries in the same format as the first. One for every file>
+ ],
+ "license": {
+ "name": <License name>,
+ "simple": <Simplified summary of license terms. Optional>
+ },
+ "by": {
+ "displayname": <User's display name>,
+ "name": <Username, without node>
+ }
+}
+
+RPC: search/<Search terms>/<Number of results requested>/<Number of results to skip for pagination>
+Returns an array of at most the requested number of items matching the given search terms
+Return format:
+[
+ {
+ "id": <Thing ID>,
+ "name": <Thing name>,
+ "description": <Thing description, markdown>,
+ "date": <Publishing date>,
+ "preview": <Path to preview 2D image>,
+ "by": {
+ "displayname": <User's display name>,
+ "name": <Username, without node>
+ }
+ },
+ <More entries in the same format as the first. One for every result>
+]
+
+RPC: peers
+Returns the list of peers a node actively federates with (includes in searches), as well as a list of blacklisted peers that will not be added even if 'automatically follow peers' is enabled
+Return format:
+{
+ "peers": [
+ <Peer domain name>,
+ <More entries in the same format as the first. One for every peer>
+ ]
+ "blacklist": [
+ <Peer domain name>,
+ <More entries in the same format as the first. One for every blacklisted peer>
+ ]
+}
+
+RPC: rpckey
+Returns the cryptographic public key the node uses to sign content stored on peers such as messages, comments, and reports, in JSON-encapsulated PEM format
+Return format:
+{
+ "public": <Public key in PEM format>
+}
+
+RPC: user/<Username>
+Returns information about the user by the given username on this node.
+Return format:
+{
+ "displayname": <Display name>,
+ "profile": <Profile, markdown>,
+ "things": [
+ {
+ "id": <Thing ID on node>,
+ "name": <Thing name>,
+ "description": <Thing description, markdown>,
+ "date": <Publishing date>,
+ "preview": <Path to preview 2D image>,
+ },
+ ],
+ "banned": <True if the user is banned>
+}
+
+RPC: comments/<Thing ID>
+Returns the comments for the given thing on this node.
+Return format:
+[
+ { // Repeated for however many top comments there are
+ "id": <Comment ID>,
+ "sender": <...>,
+ "replyto": <ID of parent comment. 0 for top comments>,
+ "message": <Comment message, markdown>,
+ "sent": <Publishing date>,
+ "removed": <True or False>,
+ "replies": [
+ <Child comments, same format as top comments>
+ ]
+ }
+]
+
+RPC: comments/<Thing ID>
+Sends a comment for the given thing on this node.
+Signed request format:
+{
+ "from": <Sender's username>,
+ "message": <Comment message, markdown>,
+ "replyto": <ID of parent comment.0 for a top comment>
+}
+Return format:
+{"status":"OK"} or {"error":<Error message>}
+
+RPC: messages/<Username>
+Sends a direct message to the user of the given username on this node.
+Signed request format:
+{
+ "from": <Sender's username>,
+ "subject": <Subject>,
+ "message": <Message, markdown>,
+ "chain": <ID of message chain/conversation>
+}
+Return format:
+{"status":"OK"} or {"error":<Error message>}
+
+RPC: report
+File a report on unfit content.
+Signed request format:
+{
+ "user": <Username of reporter>,
+ "target": <What's being reported, e.g. "thing/1" or "comment/1/5" where 1 refers to the thing and 5 to the comment>,
+ "reason": <Why it's being reported>
+}
+Return format:
+{"status":"OK"} or {"error":<Error message>}