Gridnet Radio System/API

From Nexus
Revision as of 13:51, 30 October 2018 by Shymus (Talk | contribs)

Jump to: navigation, search

← Gridnet Radio System

API Documentation

If you have scripting knowledge, you can take advantage of GridNet's API and begin creating your own tools & devices that control your network.
To navigate this wiki better, please use the navigation on the right side of the screen.


API Actions:

  • Get Network Details
  • Create Zone
  • Delete Zone
  • Zone ID to Name
  • Zone Name to ID
  • Zone List
  • Zone Channel List
  • Create Channel
  • Delete Channel
  • Channel Name to ID
  • Channel ID to Name
  • Transmit Message


How to make an API Call:

Before you can make a call to the API, you must first create and obtain an API key from your GridNet dashboard. To do this, log into your GridNet Dashboard, select the network, then navigate to "API" and select "Add API Key" to generate a new API Key.

If you aren't the owner or manager of a network and you'd like to use the API, you'll need to check with network owner about acquiring one.


Prerequisites:

You'll need to include the following global functions & variables into your script in order to successfully call an API action: 

string network_api_key = "YOUR-NETWORK-API-KEY-GOES-HERE";
key req_id;

string GenerateHash(string api_key, string data) {
    return llSHA1String(api_key+""+llStringToBase64(data));
}

SendToServer(string json_data) {
    string hash = GenerateHash(network_api_key, json_data);
    req_id = llHTTPRequest("https://gridnet.nexus-sl.net/api/index.php?",[
        HTTP_METHOD,"POST",
        HTTP_MIMETYPE,"application/x-www-form-urlencoded"
    ],"hash="+hash+"&api_key="+network_api_key+"&data="+llStringToBase64(json_data));
}

All API Calls are sent to our server in JSON format. Each function listed below contains the list of requirments that you must first set in your JSON string prior to executing the SendToServer(string json_data) function.


Get Network Details:

This function will return the following details pertaining to the specified network:

  • Network ID
  • Network Owner
  • Server Location
  • Devices Connected
  • Channel Count
  • Zone Count
  • Transmission Count

Required JSON data for API Call:

  • "action" : "get_network_details"

API Call Example:

json = llJsonSetValue("",["action"],"get_network_details");
json = llJsonSetValue(json,["network_id"],network_api_key);
SendToServer(json);

Example Response:

{
	"network_id" : "12",
	"network_owner" : "Johnny Nexen",
	"server_location" : "Silesia",
	"devices_connected" : "12",
	"channel_count" : "2",
	"zone_count" : "3",
	"transmission_count" : "50"
}


Create Zone:

This function allows you to create a new zone that is associated with the supplied API Key.

Required JSON data for API Call:

  • "action" : "create_zone"
  • "zone_name" : "The Name of Your New Zone"

API Call Example:

json = llJsonSetValue("",["action"],"create_zone");
json = llJsonSetValue(json,["zone_name"],"Fire Dept");
SendToServer(json);

Example Response:

zone_id is returned upon successful zone creation. 

{
	"zone_id" : 20
}


Delete Zone:

This function allows you to delete a zone that is associated with the supplied API Key.

Required JSON data for API Call:

  • "action" : "delete_zone"
  • "zone_id" : The 'zone_id' number

Unsure how to obtain the "zone_id"? View the API function: #Zone Name to ID:

API Call Example:

json = llJsonSetValue("",["action"],"delete_zone");
json = llJsonSetValue(json,["zone_id"],"12");
SendToServer(json);

Example Response:

{
	"success" : TRUE
}


Zone ID to Name:

This function will fetch the zone name by providing the zone ID.

Required JSON data for API Call:

  • "action" : "zone_id_to_name"
  • "zone_id" : The 'zone_id' number

Unsure how to obtain the "zone_id"? View the API function: #Zone Name to ID:

API Call Example:

json = llJsonSetValue("",["action"],"zone_id_to_name");
json = llJsonSetValue(json,["zone_id"],"12");
SendToServer(json);

Example Response:

{
	"zone_name" : "Fire Dept"
}


Zone Name to ID:

This function will fetch the zone ID by providing the zone name.

Required JSON data for API Call:

  • "action" : "zone_name_to_id"
  • "zone_name" : The name of the zone

API Call Example:

json = llJsonSetValue("",["action"],"zone_name_to_id");
json = llJsonSetValue(json,["zone_name"],"Fire Dept");
SendToServer(json);

Example Response:

{
	"zone_id" : 20
}


Zone List:

This function will return a list of all your created zones.

Required JSON data for API Call:

  • "action" : "zone_list"

API Call Example:

json = llJsonSetValue("",["action"],"zone_list");
SendToServer(json);

Example Response:

{
	"zone_list" : ["Fire Dept","Poice Dept","Medical","DOT"]
}


Zone Channel List:

This function will return a list of all the channels within the specified zone.

Required JSON data for API Call:

  • "action" : "zone_channel_list"
  • "zone_id" : "20"

Unsure how to obtain the "zone_id"? View the API function: #Zone Name to ID:

API Call Example:

json = llJsonSetValue("",["action"],"zone_channel_list");
json = llJsonSetValue(json,["zone_id"],"20");
SendToServer(json);

Example Response:

{
	"channel_list" : ["Engine - 22","Ladder-21","Engine - 21","Tanker - 21","Chief"]
}


Create Channel:

This function will create a channel within the specified zone.

Required JSON data for API Call:

  • "action" : "create_channel"
  • "zone_id" : The 'zone_id' number you'd like to create the channel under

Unsure how to obtain the "zone_id"? View the API function: #Zone Name to ID:

API Call Example:

json = llJsonSetValue("",["action"],"create_channel");
json = llJsonSetValue(json,["zone_id"],"20");
SendToServer(json);

Example Response:

{
	"channel_id" : 30
}


Delete Channel:

This function will delete the channel within the specified zone.

Required JSON data for API Call:

  • "action" : "delete_channel"
  • "zone_id" : The 'zone_id' number
  • "channel_name" : The name of the channel you'd like to delete

Unsure how to obtain the "zone_id"? View the API function: #Zone Name to ID:

API Call Example:

json = llJsonSetValue("",["action"],"delete_channel");
json = llJsonSetValue(json,["zone_id"],"20");
json = llJsonSetValue(json,["channel_name"],"Fire Dept");
SendToServer(json);


Channel Name to ID:

This function will return the channel ID of the provided channel name that is in the specified zone.

Required JSON data for API Call:

  • "action" : "channel_name_to_id"
  • "zone_id" : The 'zone_id' number that the channel is linked to
  • "channel_name" : The name of the channel that you'd like the ID for

Unsure how to obtain the "zone_id"? View the API function: #Zone Name to ID:

API Call Example:

json = llJsonSetValue("",["action"],"channel_name_to_id");
json = llJsonSetValue(json,["zone_id"],"20");
json = llJsonSetValue(json,["channel_name"],"Fire Dept");
SendToServer(json);

Example Response:

{
	"channel_id" : 30
}


Channel ID to Name:

This function will return the channel name of the provided channel ID.

Required JSON data for API Call:

  • "action" : "channel_id_to_name"
  • "channel_id" : The channel ID that you'd like the name for

API Call Example:

json = llJsonSetValue("",["action"],"channel_id_to_name");
json = llJsonSetValue(json,["channel_id"],"30");
SendToServer(json);

Example Response:

{
	"channel_name" : "Fire Dept"
}

Transmit Message

This function will transmit a message globally, zone, or channel

Required JSON data for API Call:

  • "action" : "transmit_message"
  • "transmit_level" : "GLOBAL", "ZONE", or "CHANNEL"
  • "message" : The message to be sent.
  • "network_id" : This will need to be obtained via network_details (See example below.)

Optional JSON data for API Call:

  • "callsign": This will display who sent the message.
  • "channel_id": If you are sending a message on a channel, then you need to supply the channel_id.
  • "zone_id": If you are sending a zone message, you need to supply a zone_id.

API Call Example:

string json = llJsonSetValue("",["action"],"transmit_message");
json = llJsonSetValue(json,["message"],"Hello World!");
json = llJsonSetValue(json,["transmit_level"],"global");
json = llJsonSetValue(json,["network_id"],(string)network_id);
json = llJsonSetValue(json,["callsign"],"Shymus Roffo");
SendToServer(json);

Example Response:

{
	"success" : TRUE
}


Complete API Examples

We've put together a couple of examples demonstrating how to use the GridNet API in your own scripts.

Example One - Get Network Details

string network_api_key = "INSERT-API-KEY-HERE";
key req_id;

string GenerateHash(string api_key, string data) 
{ 
    return llSHA1String(api_key+""+llStringToBase64(data)); 
}

SendToServer(string json_data)
{
    string hash = GenerateHash(network_api_key, json_data);
    req_id = llHTTPRequest("https://gridnet.nexus-sl.net/api/index.php?",[
        HTTP_METHOD,"POST",
        HTTP_MIMETYPE,"application/x-www-form-urlencoded"
    ],"hash="+hash+"&api_key="+network_api_key+"&data="+llStringToBase64(json_data));
}

default 
{
    touch_start(integer n) {
        if(llDetectedKey(0) == llGetOwner()) {
            string json = llJsonSetValue("",["action"],"get_network_details");
            SendToServer(json);
        }
    }
    http_response(key i, integer s, list m, string b) {
        if(i == req_id)
            llOwnerSay(b);
    }
}

Example Two - Create a New Zone

string network_api_key = "INSERT-API-KEY-HERE";
string json;
key req_id;
integer chan;
integer handle;

string GenerateHash(string api_key, string data) {
    return llSHA1String(api_key+""+llStringToBase64(data));
}

SendToServer(string json_data) {
    string hash = GenerateHash(network_api_key, json_data);
    req_id = llHTTPRequest("https://gridnet.nexus-sl.net/api/index.php?",[
        HTTP_METHOD,"POST",
        HTTP_MIMETYPE,"application/x-www-form-urlencoded"
    ],"hash="+hash+"&api_key="+network_api_key+"&data="+llStringToBase64(json_data));
}

default
{
    touch_start(integer n) {
        if (llDetectedKey(0) == llGetOwner()) {
            json = "";
            llListenRemove(handle);
            chan = (integer)(llFrand(1000000000.0) - 1000000000.0);
            handle = llListen(chan, "", llGetOwner(), "");
            llTextBox(llGetOwner(),"Create a New Zone\n\nPlease enter a zone name you'd like to create",chan);
        }
    }
    
    listen(integer channel, string name, key id, string message) {
        if (channel == chan && id == llGetOwner()) {
            message = llStringTrim(message,STRING_TRIM);
            if (message == "") return;
            else {
                json = llJsonSetValue("",["action"],"create_zone");
                json = llJsonSetValue(json,["zone_name"],message);
                SendToServer(json);
            }
        }
    }
    
    http_response(key i, integer s, list m, string b) {
        if (i == req_id) {
            if (llJsonValueType(b,["zone_id"]) == JSON_NUMBER) {
                string zone_id = llJsonGetValue(b,["zone_id"]);
                llOwnerSay("The zone (\""+llJsonGetValue(json,["zone_name"])+"\" - Zone ID: "+zone_id+") has successfully been created!");
            }
            else llOwnerSay("ERROR >> " + b);
        }
    }
}

Example Three - Transmit Message On Global

string network_api_key = "INSERT-API-KEY-HERE";
key req_id;
integer network_id;

string GenerateHash(string api_key, string data) { 
    return llSHA1String(api_key+""+llStringToBase64(data)); 
}

SendToServer(string json_data) {
    string hash = GenerateHash(network_api_key, json_data);
    req_id = llHTTPRequest("https://gridnet.nexus-sl.net/api/index.php?",[
        HTTP_METHOD,"POST",
        HTTP_MIMETYPE,"application/x-www-form-urlencoded"
    ],"hash="+hash+"&api_key="+network_api_key+"&data="+llStringToBase64(json_data));
}

default {
    state_entry() {
        string json = llJsonSetValue("",["action"],"get_network_details");
        SendToServer(json);
    }
    http_response(key i, integer s, list m, string b) {
        if(i == req_id) {
            network_id = (integer)llJsonGetValue(b,["network_id"]);
            state transmit_on_touch;
        }
    }
}

state transmit_on_touch {
    touch_start(integer n) {
        if(llDetectedKey(0) == llGetOwner()) {
            string json = llJsonSetValue("",["action"],"transmit_message");
            json = llJsonSetValue(json,["message"],"Hello World!");
            json = llJsonSetValue(json,["transmit_level"],"global");
            json = llJsonSetValue(json,["network_id"],(string)network_id);
            json = llJsonSetValue(json,["callsign"],"Shymus Roffo");
            SendToServer(json);
        }
    }
    http_response(key i, integer s, list m, string b) {
        if(i == req_id) {
            llOwnerSay(b);
        }
    }
}
Retrieved from "http://wiki.nexus-sl.net/wiki/index.php?title=Gridnet_Radio_System/API&oldid=560"