This post was originally published at Tutorial: Connecting to RESTful API Services

One of the powers of Corona SDK is the ability to connect to various online services to get data into your app. There are several ways of getting data in. You could use an RSS feed which is a collection of well-defined XML. Another method is SOAP which allows you to get data into apps connected to a server — however, SOAP uses a fairly complex authentication method which is challenging to deal with in Corona. Another method is REST (or RESTful) APIs which are based on standard HTTP protocols and are generally easier to authenticate.

Overview

Many services offer their data via REST and you can use the standard HTTP “verbs” to access that data:

  • GET
  • POST
  • PUT
  • DELETE

GET is used to “get” (fetch) data. POST and PUT can be both used to send data to the server, and DELETE is used to remove data (if permitted).

REST uses standard HTTP URLs to define the API. For instance, with Twitter, you could access:

https://api.twitter.com/1.1/friends/list.json

with a GET request to get a list of a user’s friends.

Most services run their APIs over a secure protocol (https://). 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 Corona (alternatively, some services allow you to request XML data by specifying .xml instead of .json).

Authentication

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:

http://username:password@api.yoursite.com/someapi/dosomething.json

This 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. Yet another method is oAUTH, and while explaining oAUTH is beyond the scope of this tutorial, Corona SDK includes an example oAUTH 1.0 module in the following local folder: /SampleCode/Networking/Twitter.

Making API Calls

In Corona SDK, your REST API calls are made using network.request(). For this API, you 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):

Alternatively, if your service can’t use basic authentication as part of the URL, you need to set up headers:

Conclusion

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 REST-based APIs from various providers.


View the original here:  

This post was originally published at Tutorial: Connecting to RESTful API Services