Using Solar2D, you can connect to various online services to get data into your app. To accomplish this, a popular option is REST (or RESTful) APIs which are based on standard HTTP protocols and are generally easy to authenticate.
Many services offer their data via REST and you can use the standard HTTP "verbs" to access that data:
GET
— Used to "get" (fetch) data.POST
/PUT
— Used to send data to the server.DELETE
— Used to remove data (if permitted).REST uses standard HTTP URLs to define the API. For instance, with Twitter, you could access the following with a GET
request to fetch a list of a user's friends:
https://api.twitter.com/1.1/friends/list.json
Let's inspect this in more detail:
Most services run their APIs over a secure protocol (https://
) which is followed by the host name.
Following the host name is commonly the API version — in this case /1.1
indicates that this is version 1.1
of the API. This allows services to change their API definitions to add/update features or change data without breaking older apps that utilize the previous version.
Following this is typically the category of functionality. In this example, all of Twitter's "friends" APIs are grouped under the /friends
family.
Finally, the specific /list
API will fetch a list of the current user's friends, conveniently formatted in JSON which is easily compatible with Solar2D (alternatively, some services allow you to request XML data by specifying .xml
instead of .json
).
Most REST APIs require some form of verification or authentication, in particular if you're trying to add or update data. Authentication can occur in various ways, for example by passing the username and password as part of the domain name:
https://username:[email protected]/someapi/dosomething.json
In this example, the username:password
method is a shortcut to using a headers table. Sometimes the username and password will be referred to as the "API Key" and "secret" and they may need to be encoded in some fashion such as MD5.
An alternate method is to use a headers table, discussed in more detail below.
Your REST API calls are made via network.request(). For this API, you need to provide a URL, an HTTP "verb", a callback function to handle the completed request, and an optional table of information in which to handle headers and data passed to the server.
Let's look at a simple example using basic authentication (no headers):
local json = require( "json" ) local function handleResponse( event ) if not event.isError then local response = json.decode( event.response ) print( event.response ) else print( "Error!" ) end return end network.request( "https://username:[email protected]/users/friends.json", "GET", handleResponse )
Alternatively, if your service can't use basic authentication as part of the URL, you need to set up headers:
local json = require( "json" ) local mime = require( "mime" ) local function handleResponse( event ) if not event.isError then local response = json.decode( event.response ) print( event.response ) else print( "Error!" ) end return end local headers = {} headers["Authentication"] = mime.b64("username:password") local params = {} params.headers = headers network.request( "https://api.yourservice.com/users/friends.json", "GET", handleResponse, params )
Every service will have its own methods to call, so you need to research the specific API calls and learn what HTTP verbs are expected, as well as which parameters. Also, each service seems to implement authentication a little differently, but this tutorial should get you started on using