(One of the classic names for British pubs is Rest and Be Thankful. It is sometimes seen as an inscription made by those who built a road, such as the section of military road which now forms the A83 near the Arrochar Alps in Scotland. However pubs, farmhouses, and other locations scattered around the British Isles bear the same name.)
You can tweet without using the Twitter app, and there are plenty of third-party apps which make a very good job of accessing social media and other remote services. This is not because they do anything particularly proprietary or clever: they merely access documented interfaces to those systems, of which the most common by far is known as RESTful.
How this helps you
Understanding RESTful architecture will give you better insight into how many of your apps work the magic that they seem to. That insight will help you solve problems when they occur. It will also help you write your own tools to access such systems, which can be cool, satisfying and very worthwhile.
What it is
Representational State Transfer (REST) is a software architecture used extensively between client apps and web servers. Using it, the server developer provides an Application Programming Interface (API) based on normal HTTP instructions (verbs) like GET and PUT, which provides access to services.
The app developer can then make calls according to that API, so that their app – and you as the user – can use the features of that service.
An explanation
That is all very abstract and nerdish.
To give an everyday example: a developer wants to write an app which will give the user a different front-end to Twitter.
Twitter offers a RESTful API which provides a large number of services which that app will use. One key feature is to compose and send a new tweet. To do that, the app has an editing box in which you compose your tweet, and a button labelled POST. When you click on that button, the app sends via HTTPS (the secure version of the regular web protocol) the following to the Twitter server:
POST https://api.twitter.com/1.1/statuses/update.json?status=I%20have%20been%20learning%20RESTful%20interfaces%20with%20Paw%202
where the text following the status= is the body of the tweet, and %20 represents a space character.
Not only that, but the app monitors trending topics for different regions. To obtain current trends for the UK, the app sends via HTTPS the following:
GET https://api.twitter.com/1.1/trends/place.json?id=23424975
(23424975 being the country ID, known as the WOEID, for the UK).
The Twitter server then sends back a response in JavaScript Object Notation (JSON), such as
[
{
"trends": [
{
"name": "#AskOrange",
"query": "%23AskOrange",
"url": "http://twitter.com/search?q=%23AskOrange",
"promoted_content": null
},
(and other trends similarly)
],
"as_of": "2015-06-18T18:18:29Z",
"created_at": "2015-06-18T18:11:26Z",
"locations": [
{
"name": "United Kingdom",
"woeid": 23424975
}
]
}
]
The app parses the JSON data and displays the trends for you.
Which services have RESTful interfaces?
ProgrammableWeb currently lists over 13,600 APIs. Although many are obscure services which few people may ever want to access, the list also includes:
- YouTube
- Flickr
- eBay
- Google Maps
- del.icio.us
- Most Google services
- Wikipedia
- Bing
- Yelp
- PayPal
- bit.ly
- Blogger
- WordPress
- iTunes stores
- BBC
- Skype
- Tumblr
- Vimeo
- Evernote
- Dropbox.
Which apps use RESTful APIs?
Almost every app that you run – under OS X or iOS – which communicates with a remote web server will use these APIs somewhere along the line. A simple example is an app with a feature using Google Translate. That will access the Google server through its RESTful API, sending it the words you want to translate and the languages concerned, and receiving the translation. Even those apps which have nothing handled remotely other than online help may use a RESTful API to access that.
What can go wrong?
One of the great advantages of REST and RESTful APIs is that they use simple HTTP (HTTPS for secure connections), coupled with URIs (URLs), which have proved to be very robust and reliable.
However things can go wrong at your (client) end or on the server, in which case regular HTTP-style errors are returned. You may have encountered these already: perhaps the most famous is Twitter’s ‘fail whale’.
Each time you send an HTTP command, such as those to post a tweet or ask for trends, to a REST server you may receive data in response too, but you should always receive an HTTP 1.1 status (success/error) code.
Status codes 200 to 206 and 300 to 307 indicate success, and will be documented in the API. The standard basic success code is usually 200, which would indicate for instance that your tweet has been successfully posted.
Status codes 400 to 417 and 500 to 505 indicate errors. Some common causes, listed by status code, include:
- 400 – bad request – the command sent was incorrect; this is usually a bug in the app at your end.
- 401 – unauthorised – you are not properly logged on, or otherwise authorised for what you requested.
- 403 – forbidden – you cannot be authorised to obtain what you requested!
- 404 – not found – usually an app bug.
- 405 – not allowed – usually an app bug.
- 500 – internal server error – the service is in trouble!
- 503 – service unavailable – could be temporary trouble with the server backend, so may be worth trying later.
How can I try it out for myself?
By far the best way is to access some of the information sources listed below, and use Paw to send some requests to a service such as Twitter. Paw provides a beautiful environment for this type of thing, and is far superior to your trying to hack your own code, to begin with.
Once you have got the hang of an API, you can then use Paw to generate the code snippets needed – in a wide range of languages including Python and Swift – and pop them into your own app.
When you do come to creating your own app to work with a RESTful API, you will need libraries to support both sending the HTTP commands and parsing the JSON responses. Those responses can be as messy and verbose as XML to handle, but thankfully most languages have good libraries or similar to help you extract the data that you need.
Although perhaps not an ideal language for working with RESTful APIs, AppleScript can send HTTP via a shell command using curl. However if you want to look at using AppleScript in this way, you will do better with David Blishen’s free JSON Helper for AppleScript, or his Twitter Scripter to access the Twitter REST API, from the App Store.
Further information
Wikipedia is always a good starting point.
The ProgrammableWeb site contains a large and general up to date index of most significant RESTful interfaces, and in most cases provides links to their API documentation. It is an essential resource in other respects too.
The Twitter REST API is documented here, and that for the iTunes and App Stores here.
Paw is detailed here, and available from there, or through the App Store (£22.99).
Allamaraju S (2010) RESTful Web Services Cookbook, O’Reilly. ISBN 978 0 596 80168 7. A thorough set of recipes for programmers working with a RESTful API.
Richardson L & Amundsen M (2013) RESTful Web APIs, O’Reilly. ISBN 978 1 449 35806 8. Also available in the iTunes Store and for Kindle. Aimed more at those who are implementing the server side, this is still excellent reading for anyone working with a RESTful API. Contains a lot of essential reference material.
Russell MA (2013) Mining the Social Web. Data Mining Facebook, Twitter, LinkedIn, Google+, GitHub, and More, O’Reilly. ISBN 978 1 449 36761 9. Also available in the iTunes Store and for Kindle. Using Python, extensive explorations of what is possible using the APIs to these popular services. However this is done using a Python virtual machine which could make producing your own apps difficult unless you use the same virtual machine.
There are several other books which detail RESTful services and clients using Java and other languages.
The Eclectic Light Company 