How to build a CakePHP 3 REST API in minutes

Step-by-step instructions for creating a full featured RESTful API using CakePHP 3.

Before We Begin

This is part one of the CakePHP 3 REST API tutorial series:

1. How to build a CakePHP 3 REST API in minutes
2. How to use a CakePHP 3 REST API
3. How to prefix route a CakePHP 3 REST API
4. How to add JWT Authentication to a CakePHP 3 REST API
5. How to make your CakePHP 3 API produce JSON API
6. How to use a CakePHP API as the data backend for Ember in 30 minutes

1. Create The Application

For this tutorial (and the follow-up posts) we will create a fresh CakePHP 3 application for our API:

• Named cake3api.app
• Connected to a database named cake3api_app
• Exposed using virtualhost http://cake3api.app

If you need help with the installation either:

• Follow the detailed installation instructions of the CakePHP Blog Tutorial
• Install cakebox and run cakebox application add cake3api.app to set up the application, database and virtual host

2. Add the CRUD plugin

Add the CRUD plugin to your application so your API will benefit of additional functionality like pagination, thin controllers and DRY best practices.

Run the following command inside your application's root directory to composer install the plugin:

composer require friendsofcake/crud:^5.0

Now run the following command to make your application use the plugin:

bin/cake plugin load Crud

3. Enable the API

a) Expose one or more controllers

Only controllers explicitly enabled for API use will be accessible through your API.

To prepare for the follow-up tutorial we will enable the CocktailsController by using the resources() method inside the / scope definition of your config/routes.php file like this:

Router::scope('/', function ($routes) {
	$routes->resources('Cocktails');
...
}

b) Configure the API

Make the default API configuration available to all controllers in your application by replacing the content of your src/Controller/AppController.php file with:

<?php
namespace App\Controller;

use Cake\Controller\Controller;

class AppController extends Controller {

    use \Crud\Controller\ControllerTrait;

    public $components = [
        'RequestHandler',
        'Crud.Crud' => [
            'actions' => [
                'Crud.Index',
                'Crud.View',
                'Crud.Add',
                'Crud.Edit',
                'Crud.Delete'
            ],
            'listeners' => [
                'Crud.Api',
                'Crud.ApiPagination',
                'Crud.ApiQueryLog'
            ]
        ]
    ];
}

c) Optionally enable extensions

Exposing your API resources requires no additional configuration, they are already fully accessible using Request Headers.

However... we will assume you want to additionally allow access to your API resources using the .json and .xml extensions so open your config/routes.php file and add the following line directly above the / scope definition:

Router::extensions(['json', 'xml']);

Stop The Clock!

That's all, you should now be able to browse to http://cake3api.app/index.json and be presented with your API's first JSON (error) response looking like this:

{
    "message": "Controller class Index could not be found.",
    "url": "\/index.json",
    "code": 404
}

Quite impressive but in all fairness... even though you now have a (very) cool API that only took minutes to create it is still pretty useless without any meaningful data to serve so this might be a good moment to dive straight into the follow-up tutorial:

How to use a CakePHP3 REST API

Additional reading

• Follow-up tutorial "How to use a CakePHP3 REST API"
• Git repository with working end state application produced by this tutorial
• FriendsOfCake CRUD plugin documentation
• The CakePHP 3 Book and CakePHP 3 API documentation