[Back to Implement a Genie Skill Backend]
Thingpedia provides a way to connect to devices that use common protocols with no additional JavaScript code. Currently, we support RSS feeds (in Atom or RSS 1.0 format), and Generic REST APIs that return JSON.
If a device needs some non-standard form of authentication or other customized computation on the return results, a Javascript code package is required, but one can still make use of the RSS, XML and standard protocol parsing code from the Thingpedia SDK.
We provide a simple interface to connect RSS feed services with Genie. You can find an example in Tutorial 2.
Five parameters are supported:
title
link
(the link to the original page, in type URL
)updated
(the updated time of the feed, in type Date
)description
picture_url
Note that some RSS feeds may only contain title
and link
. Check the RSS feed format carefully and DO NOT declare a parameter if it is not in the feed of your service.
If a device uses generic RESTful APIs and returns the data in JSON format, loader
from @org.thingpedia.generic_rest.v1
will help you connect the device easily.
In the following, let's go through a simple example: Quotes.
Quotes use the API provided by forismatic.com, which requires no authentication or developer key. The API returns a random quote in JSON format as follows:
{
"quoteText": "Always seek out the seed of triumph in every adversity.",
"quoteAuthor": "Og Mandino",
"senderName":"",
"senderLink":"",
"quoteLink":"http://forismatic.com/en/23e53ff443/"
}
To create a device for this service in Thingpedia, we define the device class as follows:
class @com.forismatic.quotes {
// tell the system the device uses generic rest
import loader from @org.thingpedia.generic_rest.v1();
// the function to return a random quote
query get(out text: String #[json_key="quoteText"],
out author: String #[json_key="quoteAuthor"])
#_[canonical=["quote", "aphorism", "maxim"]]
#_[result=["${text} . by ${author}"]]
#_[confirmation="a quote"]
#_[formatted=[{type="text",text="${text} By ${author}."}]]
#[doc="get a quote"]
#[url="http://api.forismatic.com/api/1.0/?method=getQuote&format=json&lang=en"];
}
The device class contains one query function called get
, which returns a random quote. The first four annotations should be familiar, and define the natural language interface; if not, check the guide to natural language again. We then tell the system where we get the data from. We use the annotation url
to specify the URL of the API endpoint for this function, as shown in the last line.
Then we need to choose the parameters we care about from the JSON output. In this example, we want quoteText
and quoteAuthor
. Thus, we add two output parameters, text
and author
, both in type String
. Then for each of them, we use annotation json_key
to specify the corresponding filed name from the JSON. Thus we have:
out text: String #[json_key="quoteText"]
and
out author: String #[json_key="quoteAuthor"]
If the parameter name is the same as the corresponding field name in JSON, the json_key
annotation can be omitted.
Then, put the code in manifest.tt
, add some example commands in dataset.tt
, and submit.
No Javascript backend code is needed!
[Back to Implement a Genie Skill Backend]