Add files via upload

api_doc.md

@@ -4,9 +4,94 @@ The API is a new feature that allows users to interact with external application
 
 There are presently 3 modes for data  exchange, "**msg_xfer**", "**app**", and "**raw**". 
 
+### app
+
+**app** mode is used specify the request as an app request. An app request contains a one time token generated by the sending HBLink server allowing the external application to send a one time response, without having to have login credentials on the sending server. The auth_token can only be used once.
+
+Example of app request, initiated by a user on an HBLink server via SMS:
+
+`{
+    "mode": "app",
+    "system_shortcut": "ABC",
+    "server_name": "Test HBlink Network",
+    "response_url": "http://localhost:8093/api/",
+    "auth_token": "1234567899",
+    "data": {
+        "source_id": 1234,
+        "slot": 2,
+        "msg_type": "unit",
+        "msg_format": "motorola",
+        "message": "TIME"
+    }
+}`
+mode: Set to "app" as this is an app request.
+
+system_shortcut: This is set in the sending server's config. 
+
+server_name: This is the name of the sending server.
+
+Response_url: This is the URL where we should send a response. We can initiate a POST to this URL for a response. This is the URL of the sending server's D-APRS dashboard.
+
+auth_token: This is the auth_token of the sending server. Our response must contain this. See example below.
+
+source_id : The source radio DMR ID.
+
+slot: Timeslot the message was received on.
+
+msg_type: Type of call received. This should be group or unit.
+
+msg_format: Format of the received SMS. A value of motorola is the only option at this time.
+
+message: The actual text of the SMS.
+
+Below is an example of a response that can be sent back to the sending HBLink server. The response is sent as a POST to the response:
+
+`{
+    "mode": "app",
+    "app_name": "Test HBlink App",
+    "app_shortcut": "APP",
+    "auth_token": "1234567899",
+    "data": {
+        "1": {
+            "destination_id": 3153591,
+            "slot": 0,
+            "msg_type": "unit",
+            "msg_format": "motorola",
+            "message": "The time is 21:25."
+          },
+        "2": {
+            "destination_id": 3153591,
+            "slot": 0,
+            "msg_type": "unit",
+            "msg_format": "motorola",
+            "message": "The date is April 26th, 2021."
+        }
+    }
+}`
+
+mode: Set to "app" as this is an app response.
+
+app_shortcut: This is the system shortcut of the external application. 
+
+app_name: This is the name of the responding application.
+
+auth_token: This is the auth_token that was originally sent.
+
+destination_id: DMR ID of destination radio.
+
+slot: Timeslot to send message on. A value of 0 will allow the receiving server to determine which timeslot to send the generated SMS on. This should be 0 most of the time. Other values are 1 or 2, for timeslots.
+
+msg_format: Format to generate SMS in. A value of motorola is the only option at this time.
+
+message: The actual text of the SMS.
+
+Multiple SMS can be generated from a single response, useful for sending multiple SMS as a response.
+
+### msg_xfer
+
 **msg_xfer** is used to send a message. When the D-APRS dashboard receives a msg_xfer request, it generates an SMS message and places it in HBLink's SMS sending que.
 
-With msg_xfer, there are 2 authentication types, "public" and "private". With private authentication, the requesting server (or application) must provide a username and password, specified in _authorized_users_ of the receiving server's rules.py. Public authentication is still a work in progress.
+With msg_xfer, there are 2 authentication types, "public" and "private". With private authentication, the requesting server (or application) must provide a username and password, specified in _authorized_users_ of the receiving server's rules.py. Public authentication is still a work in progress. Public authentication will allow one server to send to another server without having a shared username or password.
 
 Here is an example of a msg_xfer JSON POST using private authentication:
 
@@ -39,3 +124,29 @@ Here is an example of a msg_xfer JSON POST using private authentication:
         }
     }
 }`
+
+system_shortcut: This is set in the sending server's config. This value is used to find a username and password on the receiving server's side for authentication. This is also the shortcut that users specify in their SMS.
+
+server_name: This is the name of the sending server. 
+
+Response_url: This is the URL where we should send a response. This is important for public authentication. It is the location of the sending servers D-APRS dashboard.
+
+auth_type: pubic or private. If private, then "credentials" will be appended with the username and password.
+
+data: The dashboard forms an SMS based on the values in this field.
+
+Multiple SMS can be generated from a single request, useful for sending an SMS to multiple recipients or multiple messages to the same recipient.
+
+source_id and destination_id: The source and destination DMR ID.
+
+slot: Timeslot to send message on. A value of 0 will allow the receiving server to determine which timeslot to send the generated SMS on. This should be 0 most of the time. Other values are 1 or 2, for timeslots.
+
+msg_type: This should be group or unit. Unit for a private call, group for a group call.
+
+msg_format: Format to generate SMS in. A value of motorola is the only option at this time.
+
+message: The actual text of the SMS.
+
+## raw
+
+This is still a work in progress.