From 317de8e07537b8eb0efb4e2b453f02aadaa36776 Mon Sep 17 00:00:00 2001 From: KF7EEL Date: Mon, 26 Apr 2021 12:20:26 -0700 Subject: [PATCH] Add files via upload --- api_doc.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 113 insertions(+), 2 deletions(-) diff --git a/api_doc.md b/api_doc.md index 121aceb..c029944 100644 --- a/api_doc.md +++ b/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: @@ -38,4 +123,30 @@ Here is an example of a msg_xfer JSON POST using private authentication: "message": "text of the 2nd message" } } -}` \ No newline at end of file +}` + +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. \ No newline at end of file