Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

HTTP API Calls

It's common for Bixby capsules to communicate with an external web service to perform actions that can't be completed on the device: fetching the weather report for a given location, getting a list of nearby Italian restaurants, booking a hotel room, and so on. To use web APIs, your JavaScript action implementation's (endpoints) can take advantage of Bixby's HTTP library, and can even call them directly as remote endpoints. This small sample capsule, an adaptation of the larger "Shoe Store" simple search sample capsule, demonstrates both the HTTP library and remote endpoints.

Download the Capsule

Since this capsule demonstrates an HTTP API, it requires an API server to communicate with. The capsule is set up to use a simple Node.js-based server that we have set up for you at AppSpot, so you don't need to run the demonstration server yourself.

The server URL is set as the property remote.url in the capsule properties file. To use our already set up test server, keep it at the default value (https://bixby-http-demo.appspot.com).

Note

Note that servers for Bixby remote endpoints must be publicly accessible.

Demonstrations

This capsule includes the following short demonstrations.

Simple HTTP GET call

Training: "Find shoes with a simple HTTP call"

intent {
goal: FindShoe
}

This uses the models/actions/FindShoe.model.bxb model, whose action is implemented in code/FindShoe.js:

module.exports.function = function findShoe () {
// Read the remote.url value from capsule.properties
var response = http.getUrl(config.get('remote.url') + '/shoes', { format: 'json' });
return response;
}

This simple function uses http.getUrl() to call the API at /shoes.

HTTP GET With Query Parameters

intent {
goal: FindShoe
value: Type(Formal)
}

This also uses the FindShoe model described above, but its action is implemented in code/FindShoeFiltering.js, which is similar to the JavaScript implementation above but adds a type input which is turned into an HTTP query parameter:

module.exports.function = function findShoe (type) {
var options = {
format: 'json',
query: { type: type }
};
var response = http.getUrl(config.get('remote.url') + '/shoes', options);
return response;
}

This also demonstrates that the same action can have different JavaScript implementations based on the defining action-endpoint blocks for different accepted-inputs in the resources/base/endpoints.bxb file:

endpoints {
action-endpoints {
action-endpoint (FindShoe) {
accepted-inputs ()
local-endpoint (FindShoe.js)
}

action-endpoint (FindShoe) {
accepted-inputs (type)
local-endpoint (FindShoeFiltering.js)
}
// more endpoints
}
}

The FindShoe.js implementation is called when there are no inputs; the code/FindShoeFiltering.js endpoint is called when the input is type.

HTTP Call Returning Error

Training: "Find shoes but cause an error"

intent {
goal: FindShoeError
}

The code/FindShoeError.js implementation calls the /error API endpoint, which returns an HTTP 500 error. This is used to throw a halt effect.

HTTP Call Returning Headers

intent {
goal: FindShoeReturnHeaders
}

This demonstrates how to achieve more fine-grained control over the result of HTTP calls. The code/FindShoeReturnHeaders.js implementation also calls the /error API endpoint, but calls http.getUrl() with the returnHeaders option set to true, an error is now thrown, instead logging the error response to the console. Then it calls the /shoes API, again with returnHeaders set to true. The HTTP response is sent to the console before parsing.

HTTP POST Call

Training: "Create a shoe"

intent {
goal: CreateShoe
}

Instead of making an HTTP GET, CreateShoe.js defines a new shoe object and sends it in an HTTP POST to the /shoes API. As with the previous example, this call is made with returnHeaders set to true, and the HTTP response is sent to the console before parsing.

Remote Endpoint

Training: "Find shoes with a remote endpoint setup"

intent {
goal: FindShoeRemoteEndpoint
}

This action duplicates the Simple HTTP Get Call described above, but handles it with a remote endpoint. The /shoes API call already returns JSON formatted in the way actions need to map between JavaScript functions and Bixby models, so it can be called directly by defining a remote endpoint in the action-endpoint block:

endpoints {
action-endpoints {
action-endpoint (FindShoeRemoteEndpoint) {
accepted-inputs ()
remote-endpoint ("{remote.url}/shoes") {
method (GET)
}
}
// other endpoints
}
// more of the endpoints block
}

Because this is a remote endpoint, there is no local JavaScript implementation for the FindShoeRemoteEndpoint action needed.