So what's REST all about? Actually, it's just the way the Internet alrea= dy works. Your web browser makes a request for a web page, and the web site= responds.
However as you probably know, when you create a form in HTML, there are = two method types:
POST
You know this from HTML:
<form action=3D"http://www.bbc.co.uk/dosomething" method= =3D"GET"> <input type=3D"text" name=3D"page" value=3D"1&q= uot; /> </form>=20
With a GET request, the form variables are sent in the URL, e.g:
http://www.bbc.co.uk/dosomething?page=3D1
=20
With a POST request, the form variables are 'hidden'. They are not inclu= ded in the URL but are still sent in the request:
http://www.bbc.c=
o.uk/dosomething
(page=
=3D1)
Actually there are more than 2 methods possible for HTTP requests. Of al= l the methods available, REST APIs often use 4 methods:
All this means is that the request type (POST, GET, PUT or DELETE) is sp=
ecified in the request, in the same way as POST or GET is specified when a =
web browser sends form data to a web server.
It's really the same pro=
cess, which is partly why a REST API is said to use already-existing Intern=
et technologies.
A REST API gives a meaning to each of these request types. The meanings = are generally:
Therefore, they are sometimes referred to as 'verbs' (or 'actions') sinc= e they specify what to 'do':
We've seen that using a REST API we can specify an action: modify, retri=
eve, create or delete. So how do we specify what we want this action to be =
performed on?
That's where the 'resource' comes in. Actually this is j=
ust a unique URL which describes what to modify/retrieve/etc. In our case w=
e are performing actions on a Text Marketer account... let's say we want to=
retrieve information about credits. This is the unique URL we use to ident=
ify our REST API credits resource:
http://api.textmarketer.co.uk/services/rest/credits=20
So the URL above specifies the credits resource in the Text Marketer RES=
T API. In REST terminology it is referred to as a 'noun'. So you can see th=
at we have 'verbs' (modify/retrieve/etc) and 'nouns' (credits, etc). This i=
s just jargon to describe the action and the thing to do the action on.
So now we can combine the action/verb with the resource/thing/noun, for e=
xample 'retrieve the number of credits' is a GET request on the credits res=
ource URL:
This returns the number of credits on the account. The response will loo= k something like this if you view it in Firefox (Chrome on= ly displays the number):
<response processed_date=3D"2011-04-08T14:51:42+01:00">= ; <credits>461</credits> </response>=20
GET requests
We've seen the GET action on the credits resource returns the number of =
credits on the account. Different actions are available on different resour=
ces. Some resources may only accept a GET
action, others may only acc=
ept a POST action, and yet others may accept both.
POST requests
The credits resource allows the POST (modify) action.
Calling a POST action on the credits resource (i.e. sending a HTTP reque= st, of type POST,to the URL http://api.t= extmarketer.co.uk/services/rest/credits) allows you to transfer c= redits between accounts.
How does this work?
POST requests are for mo=
difying a resource. But how do we specify exactly what needs to be modified=
? A POST request sent to the credits resource allows us to transfer credits=
between accounts, so we need some way of specifying how many credits to tr=
ansfer and to which account.
Like an HTML form that uses a POST metho=
d, we will pass data within our POST request. In fact, if you were to build=
an HTML page with a form like this:
<form action=3D"http://api.textmarketer.co.uk/services/rest/cr= edits"=20 method=3D"POST"> Quantity:<input name=3D"quantity" value=3D"1"/>&l= t;br/> Target account:<input name=3D"target"/><br/> Target password:<input name=3D"target_password"/><br/>= ; <input type=3D"submit" name=3D"Test Credits POST"/&g= t; </form>=20
...using input fields as above to specify the number of credits and the =
account to transfer to, you could successfully make a call to the API. Howe=
ver the API will respond with XML which isn't very friendly for a web brows=
er!
So you will instead do this programmatically, within your preferre=
d programming language.
For example, this is what the same thing looks like in PHP:
<?php
$url =3D 'http://api.textmarketer.co.uk/services/rest/credits';
$data =3D array('quantity'=3D>'1', 'target'=3D>961,
=09'target_password'=3D>'mypassword',
=09'username'=3D>'u', 'password'=3D>'u');
$data =3D http_build_query($data, '', '&');
// we're using the curl library to make the request
$curlHandle =3D curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $data);
curl_setopt($curlHandle, CURLOPT_POST, 1);
$responseBody =3D curl_exec($curlHandle);
$responseInfo =3D curl_getinfo($curlHandle);
curl_close($curlHandle);
?>=20
If you're not familiar with PHP, it doesn't matter. All this illustrates= is that we are making a call to the URL http= ://api.textmarketer.co.uk/services/rest/credits using a POST request (= =E2=80=9CCURLOPT_POST=E2=80=9D in the example code), and as data we're pass= ing:
which is built into a string like this, just like you would see in a URL= , before being sent to the server as POST fields:
qua= ntity=3D1&target=3D961&target_password=3Dmypassword&username=3D= u&password=3Dp
=20
The first three arguments are what we need to specify the number of cred= its to transfer, and which account to transfer them to. We'll cover the use= rname/password arguments later.
The group resource allows a PUT request, which lets you create a group. = How to make a PUT request is not within the scope of this document.
Currently, the only resource allowing DELETE requests on Text Marketer R= EST API is the sms resource. This is used to delete a previously scheduled = SMS via API.