Difference between revisions of "HTTP API/Doing HTTP API Calls"

From SmartBots Developers Docs
Jump to: navigation, search
(Created page with "To invoke HTTP API command, you have to call SmartBots API URL with required parameters. See the full list of HTTP Bot commands here. The request c...")
 
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
To invoke HTTP API command, you have to call SmartBots API URL with required parameters. See the full list of HTTP Bot commands [[HTTP API: Bot Commands|here]].
+
{{DISPLAYTITLE: Doing HTTP API Calls}}
 +
To invoke HTTP API command, you have to call SmartBots API URL with required parameters. See the full list of HTTP Bot commands [[HTTP_API/Bot_Commands|here]].
  
 
The request can be either GET or POST. The returned value format is described down below.
 
The request can be either GET or POST. The returned value format is described down below.
 +
 +
== API call constructor ==
 +
 +
https://www.mysmartbots.com/api/testing.html - compose and test API queries using simple web form
  
 
== Passing parameters to API URL ==
 
== Passing parameters to API URL ==
  
−
Imagine you need to call [[say_chat_channel (HTTP Bot Command)|say_chat_channel]] command to say something in local chat.
+
For example, you want to call the [[HTTP_API/Bot_Commands/say_chat_channel|say_chat_channel]] command to say something in local chat.
  
−
# Take the Bot API URL: http://api.mysmartbots.com/api/bot.html
+
# Take the Bot API URL: https://api.mysmartbots.com/api/bot.html
 
# Add required parameters
 
# Add required parameters
 
# Parse the response
 
# Parse the response
Line 13: Line 18:
 
The resulting query looks like this:
 
The resulting query looks like this:
  
−
<syntaxhighlight>
+
<syntaxhighlight lang="lsl">
 
string params = llDumpList2String([
 
string params = llDumpList2String([
 
   "action="  + "say_chat_channel",
 
   "action="  + "say_chat_channel",
Line 23: Line 28:
 
   ],"&");
 
   ],"&");
  
−
llHTTPRequest("http://api.mysmartbots.com/api/bot.html",
+
llHTTPRequest("https://api.mysmartbots.com/api/bot.html",
 
   [HTTP_METHOD,"POST"], params);
 
   [HTTP_METHOD,"POST"], params);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Parsing HTTP Reply ==
+
Or using [[HTTP_API/LSL_Helper_Functions|smartbotsAPI]] LSL helper functions:
  
−
HTTP APIs return replies as a set of variables joined in the same way as URL parameters:
+
<syntaxhighlight lang="lsl">
 +
smartbotsAPI("im", [
 +
    "slname", "Glaznah Gassner",
 +
    "message", "Hi there from API"
 +
]);
 +
</syntaxhighlight>
  
−
<syntaxhighlight lang="http">
+
If you love JSON responses (see below):
−
result=FAIL&resulttext=BOT%20NOT%20EXISTS
+
 
 +
<syntaxhighlight lang="lsl">
 +
smartbotsAPIJSON("status", []);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
There are two standard return variables:
 
  
−
* '''result''' - takes one of two values:<br>OK - command completed successfully<br>FAIL - command failed
+
== Parsing API Response ==
−
* '''resulttext''' - contains the detailed explaination of failed commands
+
  
−
Other return variables may contain the query results (for example, "groups" for [[listgroups (HTTP Bot Command)|listgroups]]).
+
HTTP APIs return either JSON or URL-encoded string (by your choice). Use "dataType=json" input parameter to get JSON.
  
−
== Testing ==
+
=== JSON (added Jan 2018) ===
  
−
=== Demo and testing ===
+
The reply is being returned as a JSON string:
 +
 
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "result": "FAIL",
 +
  "resulttext": "BOT NOT EXISTS"
 +
}
 +
</syntaxhighlight>
 +
 
 +
Use [http://wiki.secondlife.com/wiki/LlJsonGetValue llJsonGetValue] to get values from the response:
 +
 
 +
<syntaxhighlight lang="lsl">
 +
    touch_start(integer total_number) {
 +
        llOwnerSay("Requesting bot status...");
 +
 
 +
        // See SmartBots "LSL Helper Functions" for smartbotsAPIJSON
 +
        smartbotsAPIJSON("status", []);
 +
    }
 +
 
 +
    http_response(key request_id, integer status, list metadata, string body) {
 +
        // llOwnerSay("API raw response: " + body);
 +
       
 +
        string status = llJsonGetValue(body, ["status"]);
 +
        ...
 +
    }
 +
</syntaxhighlight>
 +
 
 +
 
 +
=== URL-encoded string ===
 +
 
 +
The reply is being returned as a set of variables joined in the same way as URL parameters:
 +
 
 +
<syntaxhighlight lang="http">
 +
result=FAIL&resulttext=BOT%20NOT%20EXISTS
 +
</syntaxhighlight>
 +
 
 +
== Standard reply variables ==
 +
 
 +
There are two standard return variables:
  
−
You can compose and test your queries using SmartBots API Testing Suite: http://www.mysmartbots.com/api/testing.html
+
* '''result''' - can be one of:<br>OK - command completed successfully<br>FAIL - command failed
 +
* '''resulttext''' - contains the detailed explanation of failed commands
  
−
The working demo of SmartBots API is available in our office. [[BotArena Demo|Read this article]] for details.
+
Other return variables may contain the query results (for example, "groups" for [[HTTP_API/Bot_Commands/listgroups|listgroups]]).
  
 
== See also ==
 
== See also ==

Latest revision as of 14:44, 14 October 2019

To invoke HTTP API command, you have to call SmartBots API URL with required parameters. See the full list of HTTP Bot commands here.

The request can be either GET or POST. The returned value format is described down below.

API call constructor

https://www.mysmartbots.com/api/testing.html - compose and test API queries using simple web form

Passing parameters to API URL

For example, you want to call the say_chat_channel command to say something in local chat.

  1. Take the Bot API URL: https://api.mysmartbots.com/api/bot.html
  2. Add required parameters
  3. Parse the response

The resulting query looks like this: 

string params = llDumpList2String([
  "action="  + "say_chat_channel",
  "apikey="  + llEscapeURL(yourApiKey),
  "botname=" + llEscapeURL("YourBot Resident"),
  "secret="  + llEscapeURL(botSecretCode),
  "channel=" + "0",
  "message=" + llEscapeURL("Hello there!")
  ],"&");

llHTTPRequest("https://api.mysmartbots.com/api/bot.html",
  [HTTP_METHOD,"POST"], params);

Or using smartbotsAPI LSL helper functions: 

smartbotsAPI("im", [
    "slname", "Glaznah Gassner",
    "message", "Hi there from API"
]);

If you love JSON responses (see below): 

smartbotsAPIJSON("status", []);


Parsing API Response

HTTP APIs return either JSON or URL-encoded string (by your choice). Use "dataType=json" input parameter to get JSON.

JSON (added Jan 2018)

The reply is being returned as a JSON string: 

{
  "result": "FAIL",
  "resulttext": "BOT NOT EXISTS"
}

Use llJsonGetValue to get values from the response: 

    touch_start(integer total_number) {
        llOwnerSay("Requesting bot status...");

        // See SmartBots "LSL Helper Functions" for smartbotsAPIJSON
        smartbotsAPIJSON("status", []);
    }

    http_response(key request_id, integer status, list metadata, string body) {
        // llOwnerSay("API raw response: " + body);
        
        string status = llJsonGetValue(body, ["status"]);
        ...
    }


URL-encoded string

The reply is being returned as a set of variables joined in the same way as URL parameters: 

result=FAIL&resulttext=BOT%20NOT%20EXISTS

Standard reply variables

There are two standard return variables:

  • result - can be one of:
    OK - command completed successfully
    FAIL - command failed
  • resulttext - contains the detailed explanation of failed commands

Other return variables may contain the query results (for example, "groups" for listgroups).

See also

Refer to HTTP API page for information on API commands available.


Retrieved from "https://www.mysmartbots.com/dev/docs/index.php?title=HTTP_API/Doing_HTTP_API_Calls&oldid=1821"