On the most basic level a REST API consists of different urls that you can call to get and post content to a web service. This can be pictures (like Flickr) or micro blog posts (like twitter) or even videos (like youtube). When you make a request to a REST API the API responds with a chunk of XML. This XML usually represents one or more data record (they call them resources). For instance if I want to get a list of my recent twitter updates I can make a call to the following url (http://twitter.com/statuses/user_timeline.xml) and I get back an chunk of XML that represents my last 20 status updates. Taking this a step further I can also post a new status update by making a request to http://twitter.com/statuses/update.xml.

One of the key factors to take into account when working with REST APIs are the request methods used when interacting with the API. If your a little fuzzy on what request method means just think of it in terms of a web form (ie method=’post’). GET requests work off of query strings (like so http://mylink.com?id=1) where as POST requests bundle all of the data into the request itself. There is allot you can talk about as far as different request types. You can read more about it here if your still unclear on it.

Most REST APIs are setup so that when you want to get back records from the system you use a GET request. If you want to post records to the system or update an existing record you use a POST request. If your noticing a trend good for you. The convention is to work off of the verb in the sentence… so to get something you use GET and to post something you use POST. Pretty simple right.

Some APIs are set up so that when you want to delete a record you have to send a request as a DELETE method. And some APIs also use the PUT method for doing things like updates or posting files. Allot of services don’t take it to this level as it tends to just confuse people. For now just worry about GET and POST until you get everything straight in your head.

Another point to notice is that most REST APIs not only return a chunk of XML representing the data record but they also return a response status code (200 ok, 404 not found, 500 server error etc). Response status codes are a pretty hefty topic but really simple one you get it. Basically they are a numeric code that represents the status of the response (did it work or not and why). You can read more about them here.

So hopefully that wasn’t too painful. If anything that should  give you at least an introductory understanding of what to expect when you start to play with a REST API. Stay tuned for the next installment of this series when I show language specific (ruby, python) examples of using REST. Feel free to post some questions and I’ll do my best to answer them.