Tutorial - REST

    In this tutorial, we will explain how to create a simple application that provides a RESTful API using the different HTTP methods:

    • to retrieve and search data
    • POST to add data
    • PUT to update data
    • DELETE to delete data

    Defining the API

    The API consists of the following methods:

    Creating the Application

    As the application is so simple, we will not implement any full MVC environment to develop it. In this case, we will use a to meet our goal.

    The following file structure is more than enough:

    First, we need a .htaccess file that contains all the rules to rewrite the request URIs to the index.php file (application entry-point):

    1. <IfModule mod_rewrite.c>
    2.     RewriteEngine On
    3.     RewriteCond %{REQUEST_FILENAME} !-f
    4.     RewriteRule ^((?s).*)$ index.php?_url=/$1 [QSA,L]
    5. </IfModule>

    The bulk of our code will be placed in index.php. The file is created as follows:

    1. <?php
    3. use Phalcon\Mvc\Micro;
    5. $app = new Micro();
    7. // Define the routes here
    9. $app->handle(
    10.     $_SERVER["REQUEST_URI"]
    11. );

    Now we will create the routes as we defined above:

    1. <?php
    3. use Phalcon\Mvc\Micro;
    5. $app = new Micro();
    7. // Retrieves all robots
    8. $app->get(
    9.     '/api/robots',
    10.     function () {
    11.         // Operation to fetch all the robots
    12.     }
    13. );
    15. // Searches for robots with $name in their name
    16. $app->get(
    17.     '/api/robots/search/{name}',
    18.     function ($name) {
    19.         // Operation to fetch robot with name $name
    20.     }
    21. );
    23. // Retrieves robots based on primary key
    24. $app->get(
    25.     '/api/robots/{id:[0-9]+}',
    26.     function ($id) {
    27.         // Operation to fetch robot with id $id
    28.     }
    29. );
    31. // Adds a new robot
    32. $app->post(
    33.     '/api/robots',
    34.     function () {
    35.         // Operation to create a fresh robot
    36.     }
    37. );
    39. // Updates robots based on primary key
    40. $app->put(
    41.     '/api/robots/{id:[0-9]+}',
    42.     function ($id) {
    43.         // Operation to update a robot with id $id
    44.     }
    45. );
    47. // Deletes robots based on primary key
    48. $app->delete(
    49.     '/api/robots/{id:[0-9]+}',
    50.     function ($id) {
    51.         // Operation to delete the robot with id $id
    52.     }
    53. );
    55. $app->handle(
    56.     $_SERVER["REQUEST_URI"]
    57. );

    Each route is defined with a method with the same name as the HTTP method, as first parameter we pass a route pattern, followed by a handler. In this case, the handler is an anonymous function. The following route: /api/robots/{id:[0-9]+}, by example, explicitly sets that the id parameter must have a numeric format.

    Our API provides information about robots, these data are stored in a database. The following model allows us to access that table in an object-oriented way. We have implemented some business rules using built-in validators and simple validations. Doing this will give us the peace of mind that saved data meet the requirements of our application. This model file should be placed in your Models folder.

    1. <?php
    3. namespace Store\Toys;
    5. use Phalcon\Mvc\Model;
    6. use Phalcon\Mvc\Model\Message;
    7. use Phalcon\Validation;
    8. use Phalcon\Validation\Validator\Uniqueness;
    9. use Phalcon\Validation\Validator\InclusionIn;
    11. class Robots extends Model
    12. {
    13.     public function validation()
    14.     {
    15.         $validator = new Validation();
    17.         // Type must be: droid, mechanical or virtual
    18.         $validator->add(
    19.             "type",
    20.             new InclusionIn(
    21.                 [
    22.                     'message' => 'Type must be "droid", "mechanical", or "virtual"',
    23.                     'domain' => [
    24.                         'droid',
    25.                         'mechanical',
    26.                         'virtual',
    27.                     ],
    28.                 ]
    29.             )
    30.         );
    32.         // Robot name must be unique
    33.         $validator->add(
    34.             'name',
    35.             new Uniqueness(
    36.                 [
    37.                     'field'   => 'name',
    38.                     'message' => 'The robot name must be unique',
    39.                 ]
    40.             )
    41.         );
    43.         // Year cannot be less than zero
    44.         if ($this->year < 0) {
    45.             $this->appendMessage(
    46.                 new Message('The year cannot be less than zero')
    47.             );
    48.         }
    50.         // Check if any messages have been produced
    51.         if ($this->validationHasFailed() === true) {
    52.             return false;
    53.         }
    54.     }
    55. }

    Now, we must set up a connection to be used by this model and load it within our app index.php:

    1. <?php
    3. use Phalcon\Loader;
    4. use Phalcon\Mvc\Micro;
    5. use Phalcon\Di\FactoryDefault;
    6. use Phalcon\Db\Adapter\Pdo\Mysql as PdoMysql;
    8. // Use Loader() to autoload our model
    9. $loader = new Loader();
    11. $loader->registerNamespaces(
    12.     [
    14. );
    16. $loader->register();
    18. $di = new FactoryDefault();
    20. // Set up the database service
    21. $di->set(
    22.     'db',
    23.     function () {
    24.         return new PdoMysql(
    25.             [
    26.                 'host'     => 'localhost',
    27.                 'username' => 'asimov',
    28.                 'password' => 'zeroth',
    29.                 'dbname'   => 'robotics',
    30.             ]
    31.         );
    32.     }
    33. );
    35. // Create and bind the DI to the application
    36. $app = new Micro($di);

    Retrieving Data

    The first handler that we will implement is which by method GET returns all available robots. Let’s use PHQL to perform this simple query returning the results as JSON. index.php

    , allow us to write queries using a high-level, object-oriented SQL dialect that internally translates to the right SQL statements depending on the database system we are using. The clause use in the anonymous function allows us to pass some variables from the global to local scope easily.

    The searching by name handler would look like index.php:

    1. <?php
    3. // Searches for robots with $name in their name
    4. $app->get(
    5.     '/api/robots/search/{name}',
    6.     function ($name) use ($app) {
    7.         $phql = 'SELECT * FROM Store\Toys\Robots WHERE name LIKE :name: ORDER BY name';
    9.         $robots = $app->modelsManager->executeQuery(
    10.             $phql,
    11.             [
    12.                 'name' => '%' . $name . '%'
    13.             ]
    14.         );
    16.         $data = [];
    18.         foreach ($robots as $robot) {
    19.             $data[] = [
    20.                 'id'   => $robot->id,
    21.                 'name' => $robot->name,
    22.             ];
    23.         }
    25.         echo json_encode($data);
    26.     }
    27. );

    Searching by the field id it’s quite similar, in this case, we’re also notifying if the robot was found or not index.php:

    1. <?php
    3. use Phalcon\Http\Response;
    5. // Retrieves robots based on primary key
    6. $app->get(
    7.     '/api/robots/{id:[0-9]+}',
    8.     function ($id) use ($app) {
    9.         $phql = 'SELECT * FROM Store\Toys\Robots WHERE id = :id:';
    11.         $robot = $app->modelsManager->executeQuery(
    12.             $phql,
    13.             [
    14.                 'id' => $id,
    15.             ]
    16.         )->getFirst();
    20.         // Create a response
    21.         $response = new Response();
    23.         if ($robot === false) {
    24.             $response->setJsonContent(
    25.                 [
    26.                     'status' => 'NOT-FOUND'
    27.                 ]
    28.             );
    29.         } else {
    30.             $response->setJsonContent(
    31.                 [
    32.                     'status' => 'FOUND',
    33.                     'data'   => [
    34.                         'id'   => $robot->id,
    35.                         'name' => $robot->name
    36.                     ]
    37.                 ]
    38.             );
    39.         }
    41.         return $response;
    42.     }
    43. );

    Inserting Data

    Taking the data as a JSON string inserted in the body of the request, we also use PHQL for insertion index.php:

    1. <?php
    3. use Phalcon\Http\Response;
    5. // Adds a new robot
    6. $app->post(
    7.     '/api/robots',
    8.     function () use ($app) {
    9.         $robot = $app->request->getJsonRawBody();
    11.         $phql = 'INSERT INTO Store\Toys\Robots (name, type, year) VALUES (:name:, :type:, :year:)';
    13.         $status = $app->modelsManager->executeQuery(
    14.             $phql,
    15.             [
    16.                 'name' => $robot->name,
    17.                 'type' => $robot->type,
    18.                 'year' => $robot->year,
    19.             ]
    20.         );
    22.         // Create a response
    23.         $response = new Response();
    25.         // Check if the insertion was successful
    26.         if ($status->success() === true) {
    27.             // Change the HTTP status
    28.             $response->setStatusCode(201, 'Created');
    30.             $robot->id = $status->getModel()->id;
    32.             $response->setJsonContent(
    33.                 [
    34.                     'status' => 'OK',
    35.                     'data'   => $robot,
    36.                 ]
    37.             );
    38.         } else {
    39.             // Change the HTTP status
    40.             $response->setStatusCode(409, 'Conflict');
    42.             // Send errors to the client
    43.             $errors = [];
    45.             foreach ($status->getMessages() as $message) {
    46.                 $errors[] = $message->getMessage();
    47.             }
    49.             $response->setJsonContent(
    50.                 [
    51.                     'status'   => 'ERROR',
    52.                     'messages' => $errors,
    53.                 ]
    54.             );
    55.         }
    57.         return $response;
    58.     }

    The data update is similar to insertion. The id passed as parameter indicates what robot must be updated index.php:

    1. <?php
    2. use Phalcon\Http\Response;
    4. // Updates robots based on primary key
    5. $app->put(
    6.     '/api/robots/{id:[0-9]+}',
    7.     function ($id) use ($app) {
    8.         $robot = $app->request->getJsonRawBody();
    10.         $phql = 'UPDATE Store\Toys\Robots SET name = :name:, type = :type:, year = :year: WHERE id = :id:';
    12.         $status = $app->modelsManager->executeQuery(
    13.             $phql,
    14.             [
    15.                 'id'   => $id,
    16.                 'name' => $robot->name,
    17.                 'type' => $robot->type,
    18.                 'year' => $robot->year,
    19.             ]
    20.         );
    22.         // Create a response
    23.         $response = new Response();
    25.         // Check if the insertion was successful
    26.         if ($status->success() === true) {
    27.             $response->setJsonContent(
    28.                 [
    29.                     'status' => 'OK'
    30.                 ]
    31.             );
    32.         } else {
    33.             // Change the HTTP status
    34.             $response->setStatusCode(409, 'Conflict');
    36.             $errors = [];
    38.             foreach ($status->getMessages() as $message) {
    39.                 $errors[] = $message->getMessage();
    40.             }
    42.             $response->setJsonContent(
    43.                 [
    44.                     'status'   => 'ERROR',
    45.                     'messages' => $errors,
    46.                 ]
    47.             );
    48.         }
    50.         return $response;
    51.     }
    52. );

    Deleting Data

    1. <?php
    3. use Phalcon\Http\Response;
    5. // Deletes robots based on primary key
    6. $app->delete(
    7.     '/api/robots/{id:[0-9]+}',
    8.     function ($id) use ($app) {
    9.         $phql = 'DELETE FROM Store\Toys\Robots WHERE id = :id:';
    11.         $status = $app->modelsManager->executeQuery(
    12.             $phql,
    13.             [
    14.                 'id' => $id,
    15.             ]
    16.         );
    18.         // Create a response
    19.         $response = new Response();
    21.         if ($status->success() === true) {
    22.             $response->setJsonContent(
    23.                 [
    24.                     'status' => 'OK'
    25.                 ]
    26.             );
    27.         } else {
    28.             // Change the HTTP status
    29.             $response->setStatusCode(409, 'Conflict');
    31.             $errors = [];
    33.             foreach ($status->getMessages() as $message) {
    34.                 $errors[] = $message->getMessage();
    35.             }
    37.             $response->setJsonContent(
    38.                 [
    39.                     'status'   => 'ERROR',
    40.                     'messages' => $errors,
    41.                 ]
    42.             );
    43.         }
    45.         return $response;
    46.     }
    47. );

    Creating database

    Now we will create database for our application.Run SQL queries as follows:

    Using we’ll test every route in our application verifying its proper operation.

    Obtain all the robots:

    1. curl -i -X GET https://localhost/my-rest-api/api/robots
    3. HTTP/1.1 200 OK
    4. Date: Tue, 21 Jul 2015 07:05:13 GMT
    5. Server: Apache/2.2.22 (Unix) DAV/2
    6. Content-Length: 117
    7. Content-Type: text/html; charset=UTF-8
    9. [{"id":"1","name":"Robotina"},{"id":"2","name":"Astro Boy"},{"id":"3","name":"Terminator"}]

    Search a robot by its name:

    1. curl -i -X GET https://localhost/my-rest-api/api/robots/search/Astro
    3. HTTP/1.1 200 OK
    4. Date: Tue, 21 Jul 2015 07:09:23 GMT
    5. Server: Apache/2.2.22 (Unix) DAV/2
    6. Content-Length: 31
    7. Content-Type: text/html; charset=UTF-8
    9. [{"id":"2","name":"Astro Boy"}]

    Obtain a robot by its id:

    1. curl -i -X GET https://localhost/my-rest-api/api/robots/3
    3. HTTP/1.1 200 OK
    4. Date: Tue, 21 Jul 2015 07:12:18 GMT
    5. Server: Apache/2.2.22 (Unix) DAV/2
    6. Content-Length: 56
    7. Content-Type: text/html; charset=UTF-8
    9. {"status":"FOUND","data":{"id":"3","name":"Terminator"}}

    Insert a new robot:

    1. curl -i -X POST -d '{"name":"C-3PO","type":"droid","year":1977}'
    2.     https://localhost/my-rest-api/api/robots
    4. HTTP/1.1 201 Created
    5. Date: Tue, 21 Jul 2015 07:15:09 GMT
    6. Server: Apache/2.2.22 (Unix) DAV/2
    7. Content-Length: 75
    8. Content-Type: text/html; charset=UTF-8
    10. {"status":"OK","data":{"name":"C-3PO","type":"droid","year":1977,"id":"4"}}

    Try to insert a new robot with the name of an existing robot:

    1. curl -i -X POST -d '{"name":"C-3PO","type":"droid","year":1977}'
    2.     https://localhost/my-rest-api/api/robots
    4. HTTP/1.1 409 Conflict
    5. Date: Tue, 21 Jul 2015 07:18:28 GMT
    6. Server: Apache/2.2.22 (Unix) DAV/2
    7. Content-Length: 63
    8. Content-Type: text/html; charset=UTF-8
    10. {"status":"ERROR","messages":["The robot name must be unique"]}

    Or update a robot with an unknown type:

    1. curl -i -X DELETE https://localhost/my-rest-api/api/robots/4
    3. HTTP/1.1 200 OK
    4. Date: Tue, 21 Jul 2015 08:49:29 GMT
    5. Server: Apache/2.2.22 (Unix) DAV/2
    6. Content-Length: 15
    7. Content-Type: text/html; charset=UTF-8
    9. {"status":"OK"}