KOR API

This documentation provides an outline of the specifications for the KOR API.

The API receives data through channel -757982 and responds exclusively to requesting object on channel -757981 (unless specified on the request channel field); requests must be within a 15m range and utilizing JSON messages for structured communication.

Request Fields

id- [Required] last 12 characters of the target UUID. (i.e. ########-####-####-####-f60daf6b8876)

handle- A unique identifier for your requests, limited to 15 characters. This handle facilitates request tracking by returning the value response(s).

size- Defines the limit on the amount of data to return in the response. The limit constraints are a minimum of 50 and a maximum of 960.

channel- Specifies the channel on which you wish to receive responses; else defaults to -757981

fetch- JSON array where the elements can be either names of segments or JSON objects. If using a JSON object, the key would be the value of the segment name and the values as another JSON object representing the parameters. (i.e. {"Segment": {"Param1": "Value1", "Param2": "Value2"}} )

store- Similar to fetch except only an array of JSON objects are accepted. The key would be the value of the segment name and the values as another JSON object representing the parameters. (i.e. {"Segment": {"Param1": "Value1", "Param2": "Value2"}})

event- Similar to store except only a single JSON object is allowed. (i.e. {"Segment": {"Param1": "Value1", "Param2": "Value2"}} )

Response Fields

handle- An optional field which, if specified in a request, will be returned in the corresponding response. If this field is not specified in the request, it will not be present in the response. (Up to 15 characters)

status- Indicator of the request's processing status. 200 signifies a successful final response, while 206 indicates a partial response spanning multiple messages.

size- Specifies the number of responses expected for the full body.

part- The index of the response provided, starting from 1 and going to size.

data- Contains the data of the response (which may only be part of a response body).

---

Example I

Request on -757982

{"id": "f60daf6b8876", "handle": "TEST", "fetch": ["colors"]}

Returns on -757981

{"handle":"TEST","status":200,"data":"{"colors":{"color":"<1.00000, 0.00000, 0.00000>","color-2":"<0.56000, 0.87500, 1.00000>","color-3":"<1.00000, 0.00000, 0.00000>","color-4":"<1.00000, 0.00000, 0.00000>"}}"}

---

Example II

Request on -757982

{"id": "f60daf6b8876", "channel": -4242, "fetch": ["designation"]}

Returns on -4242

{"status": 200,"data":"{\"designation\":\"Flosk 'Kobot'\"}"}

---

Example III

Request on -757982

{"id": "f60daf6b8876", "handle": "ME", "channel": -4242, "size": 50, "fetch": ["colors", "designation"]}

Returns on -4242

{"handle": "ME", "status": 206, "size": 5, "part": 1, "data": "{\"colors\":{\"color\":\"<1.00000, 0.00000, 0.0000"}
{"handle": "ME", "status": 206, "size": 5, "part": 2, "data": "0>\",\"color-2\":\"<0.56000, 0.87500, 1.00000>\","}
{"handle": "ME", "status": 206, "size": 5, "part": 3, "data": "\"color-3\":\"<1.00000, 0.00000, 0.00000>\",\"color"}
{"handle": "ME", "status": 206, "size": 5, "part": 4, "data": "-4\":\"<1.00000, 0.00000, 0.00000>\"},\"designatio"}
{"handle": "ME", "status": 200, "size": 5, "part": 5, "data": "n\":\"Flosk 'Kobot'\"}"}

---

Example Script

integer KORI = -757982; // KOR API
string JSON = "";

default
{
    state_entry()
    {
        key kTarget = llGetOwner();
        list lTarget = llParseString2List((string)kTarget, ["-"], []);
        
        // prepare request data
        string jSubsystemParams = llList2Json(JSON_OBJECT, [
                "include", llList2Json(JSON_ARRAY, ["id", "label"])
                ]);
        string jSubsystemSegment = llList2Json(JSON_OBJECT, [
            "subsystems", jSubsystemParams
            ]);
        
        // fetch "colors" and "subsystems"
        string jFetchSegments = llList2Json(JSON_ARRAY, [
            "colors", jSubsystemSegment
            ]);
        
        string jRequest = llList2Json(JSON_OBJECT, [
            "id", llList2String(lTarget, -1), 
            "fetch", jFetchSegments
            ]);

        // jRequest = {"id":"f60daf6b8876","fetch":["colors",{"subsystems":{"include":["id","label"]}}]}

        llListen(KORI + 1, "", NULL_KEY, ""); // default response channel
        llRegionSayTo(kTarget, KORI, jRequest);
    }

    listen(integer iChan, string sName, key kUuid, string sJson)
    {
        // collect responses returned while 206
        JSON += llJsonGetValue(sJson, ["data"]);
        if(206 == (integer)llJsonGetValue(sJson, ["status"])) return;
        
        // response status should have been 200
        llOwnerSay(JSON);
        JSON = "";
    }
}

Example Output (clean)

{
  "colors": {
    "color": "<1.00000, 0.00000, 0.00000>",
    "color-2": "<0.56000, 0.87500, 1.00000>",
    "color-3": "<1.00000, 0.00000, 0.00000>",
    "color-4": "<1.00000, 0.00000, 0.00000>"
  },
  "subsystems": [
    {
      "id": "subsys.audio",
      "label": "Audio"
    },
    {
      "id": "policy.comms",
      "label": "Comms"
    },
    {
      "id": "subsys.core",
      "label": "Core"
    },
    {
      "id": "subsys.optics",
      "label": "Optics"
    },
    {
      "id": "subsys.qtt",
      "label": "QTT"
    },
    {
      "id": "subsys.servos",
      "label": "Servos"
    }
  ]
}

Example Script II

Fetching Power Status

integer KORI = -757982; // KOR API
string JSON = "";

default
{
    state_entry()
    {
        key kTarget = llGetOwner();
        list lTarget = llParseString2List((string)kTarget, ["-"], []);
        
        // prepare request data
        string jPowerParams = llList2Json(JSON_OBJECT, [
                "include", llList2Json(JSON_ARRAY, ["source"])
                ]);
        string jPowerSegment = llList2Json(JSON_OBJECT, [
            "power", jPowerParams
            ]);
        
        // fetch "power"
        string jFetchSegments = llList2Json(JSON_ARRAY, [
            jPowerSegment
            ]);
        
        string jRequest = llList2Json(JSON_OBJECT, [
            "id", llList2String(lTarget, -1), 
            "fetch", jFetchSegments
            ]);

        // jRequest = {"id":"f60daf6b8876","fetch":[{"power":{"include":["source"]}}]}

        llListen(KORI + 1, "", NULL_KEY, ""); // default response channel
        llRegionSayTo(kTarget, KORI, jRequest);
    }

    listen(integer iChan, string sName, key kUuid, string sJson)
    {
        // response returned
        JSON += llJsonGetValue(sJson, ["data"]);
        if(206 == (integer)llJsonGetValue(sJson, ["status"])) return;
        
        llOwnerSay(JSON);
        JSON = "";
    }
}

Output: (clean)

{
   "power":{
      "source":{
         "charge":9458330,
         "chargeCapacity":10000000,
         "powerType":"PLASMA",
         "capabilities":[
            "IONIZATION"
         ],
         "thermalStat":{
            "objectMass":12,
            "energyJoules":26711,
            "temperature":1.3925833333333342
         }
      }
   }
}