A growing trend across applications is the support for REST API's; they're easy to develop, implement and extend across multiple platforms.

If you aren't familiar with the principles behind a REST (Representational State Transfer) API then you can read full details on Wikipedia but at an abstract overview, it is model which allows external applications to interact with your data. REST isn't just restricted to the concept of within an API either, but in this article we'll focus on handling REST in the context of an API.

The RESTful process

All APIs need to accept and handle requests. Typically you'll use a well-defined URL schema (as I'll demonstrate below for the STV API for my election system discussed here: ) and your API may handle data differently (do you use JSON, XML, etc). When Twitter first introduced the notion of its API, it handled responses through XML and JSON and gave the user the flexibility to specify the response type, however most companies now return only JSON (which is my preference anyway as it is supported and works perfectly alongside Javascript or any Javascript kit like jQuery).

In conjunction with the request URL, REST takes advantage of the well-defined HTTP standards to specify the request method allowing us to use GET, POST, PUT and DELETE. 

What do the requests mean?

Each request method is used to handle a stereotypical action:

  • GET - fetch or load data
  • POST - create or insert data
  • PUT - update our data
  • DELETE - remove our data

We can take the following URL schema:

  • GET /api/elections - list all the elections
  • GET /api/election/1 - list the details for election with ID of 1
  • POST /api/election - create a new election
  • PUT /api/election/1 - update details for election with ID of 1
  • DELETE /api/election/1 - delete the election with ID of 1

How do we handle responses?

Simple requests means simple responses without us having to get our fingers messy. Every response has a response body and a status code which tells us about the status of our request and if we were successful or not. The advantage of this is that we don't need to define our own error schema for the API and we can use the already defined HTTP standard (again, yes!).

Common status codes are:

  • 201 - Succesful
  • 400 - Bad Request
  • 404 - Not Found
  • 500 - Internal Server Error
  • 501 - Not Implemented
  • 503 - Service is Unavailable

For the full list check out Wikipedia: List of HTTP Status Codes.

Implementing your own REST API

Just like most other scenarios, there are plenty of pre-designed frameworks to get you started whilst alternatively you can always write one yourself from scratch. To begin with, I'll consider Slim.

Slim is a PHP micro-framework that allows you to rapid-prototype and develop your API. It's simple but powerful.

# Create the instance
$app = new \Slim\Slim();
# Define a GET method
$app->get('/api/election/:ID', function($ID) {
    echo "Election: $ID";
});
# Define a POST method
$app->post('/api/election/', function() {
    echo 'Check POST for errors, etc..';
});
# Define a PUT method
$app->put('/api/election/:ID', function($ID) {
    echo 'Update election identified by $ID';
});
# Define a DELETE method
$app->delete('/api/election/:ID', function($ID) {
    echo 'Delete the election identified by $ID';
});
# Run the application 
$app->run();

When we run the application, the framework will detect our request method and our URI to determine the correct statement we want to execute - known as a PHP router class. Slim also provides template rendering, secure cookies, HTTP caching, logging and custom error handling/debugging and a simple configuration. If you've never used it, it is definitely worth a look at. For full documentation please visit here.

Have you used a REST framework or Slim? What are your opinions on it? Let me know by mentioning #ALJTMedia on Twitter or leave a comment on our Facebook or Google+ page.

Other Resources

0
Ignite your brand, utilise user-generated content no matter where you or your audience are ›