What in the world is an API ?

In computer programming, an application programming interface (API) specifies a software component in terms of its operations, their inputs and outputs and underlying types. Its main purpose is to define a set of functionalities that are independent of their respective implementation, allowing both definition and implementation to vary without compromising each other.

Let's talk about REST

"A RESTful web service (also called a RESTful web API) is a web service implemented using HYYP and the principles of REST. It's a collection of resources..."
- Wikipedia

Let's talk about REST

• REST uses standard HTTP methods to perform specific actions
• GET => Read
• POST => Create
• PUT => Update
• DELETE => Delete really ??

There is not a right way to do things...

but there are a series of good practives that you can follow :

• Best practices Vinay Sahni
• JSON-API standard jsonapi.org
• Building API's you wont hate by Phil Sturgeon

Standards are not inforced...

Your API will probably still work if you dont follow them...

but it will eventually catch you up !

Laravel makes it really easy for you !

// Simple resource routing
Route::resource('/contacts', 'ContactsController');

		

It's always nice to version your API

GET /v1/contacts

Route::group(array('prefix' => 'v1'), function()
{
		Route::resource('/contacts', 'ContactsController');
});

		

Setting up the Controller

php artisan controller:make ContactsController

	

Route::resource('/contacts', 'ContactsController');

	

class ContactsController extends BaseController {

	public function index() {}          // GET    /
	public function create() {}         // GET    /create
	public function store() {}          // POST   /
	public function show($id) {}        // GET    /1
	public function edit($id) {}        // GET    /1/edit
	public function update($id) {}      // PUT    /1
	public function destroy($id) {}     // DELETE /1

}

	

php artisan routes

	

Eloquent

class Contact extends Eloquent {}

	

Use the right codes for the right situation

200: The request was successful.
201: The resource was successfully created.
204: The request was successful, but we did not send any content back.
400: The request failed due to an application error, such as a validation error.
401: An API key was either not sent or invalid.
403: The resource does not belong to the authenticated user and is forbidden.
404: The resource was not found.
500: A server error occurred.

	

Now we need to respond with JSON

	

// General HttpException handler
App::error(function(Symfony\Component\HttpKernel\Exception\HttpException $e, $code)
{
	$headers = $e->getHeaders();

	switch ($code)
	{
		case 401:
			$default_message = 'Invalid API key';
			$headers['WWW-Authenticate'] = 'Basic realm="REST API"';
		break;

		case 403:
			$default_message = 'Insufficient privileges to perform this action';
		break;

		case 404:
			$default_message = 'The requested resource was not found';
		break;

		default:
			$default_message = 'An error was encountered';
	}

	return Response::json(array(
		'error' => $e->getMessage() ?: $default_message,
	), $code, $headers);
});

	

Some custom exception

	

App::error(function(ErrorMessageException $e)
{
	$messages = $e->getMessages()->all();

	return Response::json(array(
		'error' => $messages[0],
	), 400);
});

// NotFoundException handler
App::error(function(NotFoundException $e)
{
	$default_message = 'The requested resource was not found';

	return Response::json(array(
		'error' => $e->getMessage() ?: $default_message,
	), 404);
});

// PermissionException handler
App::error(function(PermissionException $e)
{
	$default_message = 'Insufficient privileges to perform this action';

	return Response::json(array(
		'error' => $e->getMessage() ?: $default_message,
	), 403);
});

class ErrorMessageException extends RuntimeException {}
class NotFoundException extends RuntimeException {}
class PermissionException extends RuntimeException {}

	

GET /contacts/yehaa

HTTP/1.1 404 Not found
Content-Type: application/json

{
	"error": "The requested resource was not found";
}


	

Let's stick to HTTP authentication

First we neet to create an API key...

	

		/**
	 * Generate a random, unique API key.
	 *
	 * @return string
	 */
	public static function createApiKey()
	{
		return Str::random(32);
	}

	

	

User::creating(function($user)
{
	$user->api_key = User::createApiKey();
});

	

Now, we create a filter

	

	Route::filter('api.auth', function()
{
	if (!Request::getUser())
	{
		App::abort(401, 'A valid API key is required');
	}

	$user = User::where('api_key', '=', Request::getUser())->first();

	if (!$user)
	{
		App::abort(401);
	}

	Auth::login($user);
});


	

Laravel Magic at it's purest

	

Route::filter('api.limit', function()
{
	$key = sprintf('api:%s', Auth::user()->api_key);

	// Create the key if it doesn't exist
	Cache::add($key, 0, 60);

	// Increment by 1
	$count = Cache::increment($key);

	// Fail if hourly requests exceeded
	if ($count > Config::get('api.requests_per_hour'))
	{
		App::abort(403, 'Hourly request limit exceeded');
	}
});