Luna Service API Introduction

webOS TV provides the Luna Service that consists of essential services and features for webOS TV. Each service and feature provides application programming interface (API) and its methods for you. With these Luna service APIs, you can request data from the proper service and use the response information to your apps.

Supported Luna service APIs

webOS TV currently provides the following APIs. More services and APIs are on their way.

API compatibility on webOS TV device

The following table shows the support for each API on webOS TV platform.

API compatibility on webOS TV simulator

The following table shows the current support for each API on the simulator.

API compatibility on webOS TV emulator

The following table shows the current support for each API on the emulator.

Essentials of an API service call

Service URI

The Service URI is the URI to the service, in the form:

luna://service name

For example,

luna://com.webos.mediadb

Parameters

Parameters are service request options and are passed as a JSON object. These consist of properties required for the service request as well as a few reserved properties that are common to all service requests.

Method name

The API service method that is called. The method name can be passed as part of the URI or could be passed separately as a property of the parameters object.

Subscribe property

The `subscribe` property is a reserved property of the parameter object and can be sent to services that allow subscriptions. If the `subscribe` property is set to `true`, the method remains in memory and returns responses either at periodic intervals or when its data is updated.

Resubscribe property

The `resubscribe` property is a reserved property of the parameter object and is used along with the `subscribe` property. If `resubscribe` is set to `true`, it resubscribes to a method after a failure has occurred.

Success callback

The `onSuccess` property is a reserved property of the parameter object and is used to set a callback function that is called when a request has been successful. This function receives a JSON object containing the service's response data.

Failure callback

The `onFailure` property is a reserved property of the parameter object and is used to set a function that is called when a request has failed. This function receives a JSON object containing the service's error details.

Complete callback

The `onComplete` property is a reserved property of the parameter object and is used to set a function that is called when a request is complete (regardless of its success or failure).

Request object

The object returned by a service request call. It can be used to cancel the service request and any associated subscription.

Response object

The JSON object contains the service's response data and has a reserved property `returnValue` to indicate the success or failure of a call.

If `returnValue` is set to `false`, it means the call failed, and the response object may contain further properties such as the `errorCode` and `errorText` that give more information about the error.

If `returnValue` is `true`, the call is a success, and the response object may have additional properties depending on the API call being made. If the `subscribe` property in the parameters was set to `true`, the response object returns a property `subscribed` to indicate the success of the subscription. A value of `true` in `subscribed` indicates that the subscription was a success.

Calling webOS services from any web application

webOSTV.js is a portable library specialized in webOS TV. Any application can include webOSTV.js, and you can make webOS service calls using the `webOS.service.request` API.

From webOS TV 4.0, we provide the webOSTV.js library instead of the webOS.js library. Bootplate-web templates contain the webOSTV.js library in its `webOSTVjs-x.x.x` directory. You can add this library to your app as below:

<script type="text/javascript" src="webOSTVjs-1.1.1/webOSTV.js"></script>

For more details about webOSTV.js, see the webOSTV.js guide. The following code snippet shows how you can call a webOS service using webOSTV.js.

var request = webOS.service.request("luna://com.mycom.helloworld.service", {
    method:"hello",
    parameters: {"input": inputMessage},

    onSuccess: function (args) {
        //TO-DO
    },

    onFailure: function(inError) {
        //TO-DO
    },

    onComplete: function(inResponse) {
        //....
    },

    subscribe: subscribeStatus ,
    resubscribe: resubscribeStatus
});

Calling webOS services using Enact

To call webOS services using the Enact framework, refer to the following documents.