Build simple REST API with PHP – Part 3

By emiviada in API, HTTP, PHP, REST, Slim, Web Development 4 Comments

This is the last part of our post serie about building simple REST API with PHP. We can find the two previous ones here:

  1. Part 1
  2. Part 2

In the last part we’ll add Middlewares to add more features to our API and also customize some error outputs to make them more consumable.

 

Middlewares

We will add the following three middlewares:

  • ContentTypes: Parses JSON-formatted body from the client (the innermost);
  • JSON: utility middleware for “JSON only responses” and “JSON encoded bodies”;
  • Authentication (outermost).

 

ContentType Middleware

For the ContentType middleware we’ll use an existing Slim middleware, so we just need to add it in our bootstrap.php file:

1
2
3
4
...
// Middlewares
// Content Type (inner)
$app->add(new \Slim\Middleware\ContentTypes());

This middleware intercepts the HTTP request body and parses it into the appropriate PHP data structure if possible; else it returns the HTTP request body unchanged. This is particularly useful for preparing the HTTP request body for an XML or JSON API.

 

JSON Middleware

Our JSON middleware achieves two best practices: “JSON only responses” and “JSON encoded bodies”. So, lets add it in our bootstrap.php file:

1
$app->add(new API\Middleware\JSON());

As we can see if we review a classic Middleware class, the call() method of a Slim middleware is where the action takes place. Here is our JSON middleware class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<?php
namespace API\Middleware;

class JSON extends \Slim\Middleware
{
    public function call()
    {
        try {
            // Force response headers to JSON
            $this->app->response->headers->set('Content-Type', 'application/json');

            $method = strtolower($this->app->request->getMethod());
            $mediaType = $this->app->request->getMediaType();
            $body = $this->app->request()->getBody();
            // Validate JSON format
            if (!$this->app->isJSON($body)) {
                throw new \Exception("JSON data is malformed", 400);
            }
            if (in_array($method, array('post', 'put', 'patch')) && '' !== $body) {
                if (empty($mediaType) || $mediaType !== 'application/json') {
                    $this->app->halt(415);
                }
            }
        } catch (\Exception $e) {
            echo json_encode(array(
                    'code' => $e->getCode(),
                    'message' => $e->getMessage()
                ),
                JSON_PRETTY_PRINT
            );
            exit;
        }
    }

    $this->next->call();
}

If the request method is one of the write-enabled ones (PUT, POST, PATCH) the request content type header must be application/json, if not the application exits with a 415 Unsupported Media Type HTTP status code. If all is right the statement $this->next->call() runs the next middleware in the chain.

 

Authentication Middleware

To authenticate our api users we’ll use a third-party library: JWT Authentication Middleware for Slim

1
2
3
$app->add(new \Slim\Middleware\JwtAuthentication([
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

This middleware implements JSON Web Token Authentication for Slim Framework. It does not implement OAuth 2.0 authorization server nor does it provide ways to generate, issue or store authentication tokens. It only parses and authenticates a token when passed via header or cookie.

 

Pretty outputs for Errors

Our API should show useful error messages in pretty format. We need a minimal payload that contains an error code and message. With Slim we can redefine both 404 errors and server errors with the $app->notFound() and $app->error() method respectively.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
$app->notFound(function () use ($app) {

    $mediaType = $app->request->getMediaType();
    $isAPI = (bool) preg_match('|^/api/v.*$|', $app->request->getPath());

    if ('application/json' === $mediaType || true === $isAPI) {

        $app->response->headers->set('Content-Type', 'application/json');

        echo json_encode(
            array(
                'code' => 404,
                'message' => 'Not found'
            )
        );

    }
});

For other errors we can use and customize the error() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
$app->error(function (\Exception $e) use ($app, $log) {

    $mediaType = $app->request->getMediaType();
    $isAPI = (bool) preg_match('|^/api/v.*$|', $app->request->getPath());

    // Standard exception data
    $error = array(
        'code' => $e->getCode(),
        'message' => $e->getMessage()
    );

    // Custom error data (e.g. Validations)
    if (method_exists($e, 'getData')) {
        $errors = $e->getData();
    }
   
    if (!empty($errors)) {
        $error['errors'] = $errors;
    }

    $log->error($e->getMessage());
    if ('application/json' === $mediaType || true === $isAPI) {
        $app->response->headers->set('Content-Type', 'application/json');
        echo json_encode($error);
    }
});

The $app->error() method receives the thrown exception as argument and print it in a pretty way.

Well that’s, we’ve developed a basic API with common best practices. I hope these post series are helpful for you guys.

Build simple REST API with PHP – Part 2

By emiviada in API, HTTP, PHP, REST, Slim, Web Development 0 Comment

In our first part of this post series we saw how to bootstrap our API and we defined the end points for it. Now, we’ll add the necessary logic to make our end points to work.

End Points

GET /users

Here we will get ALL our existing users.

1
2
3
4
5
6
7
8
9
10
11
12
13
// GET route for all users
$app->get('/users', function () use ($app, $log) {
    $users = array();
    $results = \ORM::forTable('user');

    $users = $results->findArray();

    // Here, we can add sorting, filtering and/or searching logic

    $output = array('code' => 200, 'data' => $users);
    echo json_encode($output, JSON_PRETTY_PRINT);
    return;
});

 

GET /users/:id

Given a user ID we return that user if exists, if not we return a 404 error.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// GET route
$app->get('/users/:id', function ($id) use ($app, $log) {
    $user = \ORM::forTable('user')
        ->findOne($id);

    if ($user) {
        $user = $user->asArray();
           
        $output = array('code' => 200, 'data' => array($user));
        echo json_encode($output, JSON_PRETTY_PRINT);
        return;
    }
   
    $app->notFound();
});

Observe how the “:id” url parameter is passed as an argument of the callable function.

 

POST /users

Now, sending POST data to the /users end point we will be able to create a new User.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// POST route, for creating
$app->post('/users', function () use ($app, $log) {
    // Get POSTed data in body
    $body = $app->request()->getBody();

    // Validate data here

    $user = \ORM::for_table('user')->create();
    $user->set($body);
    if ($user->save() === true) {
        $output = array(
            'code' => 200,
            'data' => array($user->asArray())
        );
    echo json_encode($output, JSON_PRETTY_PRINT);
        return;
    } else {
        throw new \Exception('Something went wrong.');
    }
});

 

PUT /users/:id

Update an existing user with passed data given a user ID.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// PUT route, for updating
$app->put('/users/:id', function ($id) use ($app, $log) {
    $user = \ORM::forTable('user')
        ->findOne($id);

    if ($user) {
        $body = $app->request()->getBody();

        // Validate data here

        $user->set($body);
        if ($user->save() === true) {
            $user = $user->asArray();
           
            $output = array('code' => 200, 'data' => array($user));
            echo json_encode($output, JSON_PRETTY_PRINT);
            return;
        } else {
            throw new \Exception('Something went wrong.');
        }
    }
   
    $app->notFound();
});

 

DELETE /users/:id

Here given a user ID we will delete the user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// DELETE route
$app->delete('/users/:id', function ($id) use ($app, $log) {
    $user = \ORM::forTable('user')
        ->findOne($id);

    if ($user) {
        $user->delete();
        if ($user->save() === true) {
            $output = array('code' => 200, 'data' => array());
            echo json_encode($output, JSON_PRETTY_PRINT);
            return;
        } else {
            throw new \Exception('Something went wrong.');
        }
    }
   
    $app->notFound();
});

 

User’s Phonenumbers

Now, we will define the end points for our second collection Phonenumbers.

GET /users/:id/phonenumbers

In this end point we will return all the associated phonenumbers to a user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// GET route for all users's phonenumbers
$app->get('/users/:id/phonenumbers', function ($id) use ($app, $log) {
    $user = \ORM::forTable('user')
        ->findOne($id);

    if ($user) {
        $data = $user->asArray();
        $phonenumbers = \ORM::forTable('phonenumber')
            ->where('user_id', $id)
            ->orderByDesc('id')
            ->findArray();
        $data['phonenumbers'] = $phonenumbers;
        $output = array('code' => 200, 'data' => $data);
        echo json_encode($output, JSON_PRETTY_PRINT);
        return;
    }
   
    $app->notFound();
});

 

GET /users/:id/phonenumbers/:pid

Now given a user ID and a phone ID we will return that specific phonenumber for the given user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// GET route for specific user's phonenumber
$app->get('/users/:id/phonenumbers/:pid', function ($id, $phoneId) use ($app, $log) {
    $user = \ORM::forTable('user')
        ->findOne($id);

    if ($user) {
        $data = $user->asArray();
        $phonenumber = \ORM::forTable('phonenumber')
            ->where('user_id', $id)
            ->andWhere('id', $phoneId)
            ->findOne();
        if ($phonenumber) {
            $data['phonenumber'] = $phonenumber;
            $output = array('code' => 200, 'data' => $data);
            echo json_encode($output, JSON_PRETTY_PRINT);
            return;
        }
    }
   
    $app->notFound();
});

 

POST /users/:id/phonenumbers

With this end point we will be able to create/add a phonenumber to a user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// POST route, for creating a new user's phonenumber
$app->post('/users/:id/phonenumbers', function ($id) use ($app, $log) {
    $user = \ORM::forTable('user')
        ->findOne($id);

    if ($user) {
        $data = $user->asArray();
        // Get POSTed data in body
        $body = $app->request()->getBody();

        // Validate data here

        $phonenumber = \ORM::for_table('phonenumber')->create();
        $phonenumber->set($body);
        if ($phonenumber->save() === true) {
            $data['phonenumber'] = $phonenumber->asArray();
            $output = array(
                'code' => 200,
                'data' => $data
            );
        echo json_encode($output, JSON_PRETTY_PRINT);
            return;
        } else {
            throw new \Exception('Something went wrong.');
        }
    }
   
    $app->notFound();
});

 

PUT /users/:id/phonenumbers/:pid

PUT route to update a user’s phonenumber.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// PUT route, for updating a user's phonenumber
$app->put('/users/:id/phonenumbers/:pid', function ($id, $phoneId) use ($app, $log) {
    $user = \ORM::forTable('user')
        ->findOne($id);

    if ($user) {
        $data = $user->asArray();
        $phonenumber = \ORM::forTable('phonenumber')
            ->findOne($phoneId);

        if ($phonenumber) {
            $data = $user->asArray();
            // Get POSTed data in body
            $body = $app->request()->getBody();

            // Validate data here

            $phonenumber->set($body);
            if ($phonenumber->save() === true) {
                $data['phonenumber'] = $phonenumber->asArray();
                $output = array(
                    'code' => 200,
                    'data' => $data
                );
            echo json_encode($output, JSON_PRETTY_PRINT);
                return;
            } else {
                throw new \Exception('Something went wrong.');
            }
        }
    }
   
    $app->notFound();
});

 

DELETE /users/:id/phonenumbers/:pid

And at the end, we define the route to delete an specific user’s phonenumber.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// DELETE route, for delete a user's phonenumber
$app->delete('/users/:id/phonenumbers/:pid', function ($id, $phoneId) use ($app, $log) {
    $user = \ORM::forTable('user')
        ->findOne($id);

    if ($user) {
        $phonenumber = \ORM::forTable('phonenumber')
            ->findOne($phoneId);
        if ($phonenumber) {
            $phonenumber->delete();
            if ($phonenumber->save() === true) {
                $output = array('code' => 200, 'data' => array());
                echo json_encode($output, JSON_PRETTY_PRINT);
                return;
            } else {
                throw new \Exception('Something went wrong.');
            }
        }
    }
   
    $app->notFound();
});

 

Well, we finished defining all our end points to interect against our API. At this point we have a basic API working but still there are thing to do to make it more fully functional. For instance, what if we want to make our API secure? We should add authentication, and we’ll do it using really great Slim’s functionality Middlewares. Also, we can ensure all our requests/responses are being talking JSON and/or add some rate limit to don’t allow overwhelming our API.

In the next and last post we will cover all this. See you soon! :D.

Build simple REST API with PHP – Part 1

By emiviada in API, HTTP, PHP, REST, Slim, Web Development 2 Comments

A web API (Application Programming Interface) is a set of programming instructions to access software applications and consume and share data between them. Developing your own API you can benefit both you and your users and for that we will write about how to build a simple REST API with PHP.

To build our API we will use Slim micro framework. As they mention in their site

Slim is a PHP micro framework that helps you quickly write simple yet powerful web applications and APIs.

As we said above an API is an Application Programming Interface for what it should be friendly, simple and easy to use. To help other developers to use our API we should consider writing a good documentation about it, or at least, a very explanatory README file. Such documentation need to be a summary of the service’s scope and the list of methods and access points.

Following the key principles of REST, each resource is represented by a URL, where the action is the HTTP verb used to access it.

A full list of access points is listed below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
URL                               HTTP Verb    Operation
/api/users                        GET          Returns an array of users
/api/users/:id                    GET          Returns the user with id of :id
/api/users                        POST         Adds a new user and return it with its id
/api/users/:id                    PATCH        Partially updates the user with id of :id
/api/users/:id                    PUT          Updates the complete user with id of :id
/api/users/:id                    DELETE       Deletes the user with id of :id

/api/users/:id/phonenumbers       GET          Returns the phonenumbers for the user with id of :id
/api/users/:id/phonenumbers/:pid  GET          Returns the phonenumber with id of :pid for the user with id of :id
/api/users/:id/phonenumbers       POST         Adds a new phonenumber for the user with id of :id
/api/users/:id/phonenumbers/:pid  PATCH        Partially updates the phonenumber with id of :pid for the user with id of :id
/api/users/:id/phonenumbers/:pid  PUT          Updates the phonenumber with id of :pid for the user with id of :id
/api/users/:id/phonenumbers/:pid  DELETE       Deletes the phonenumber with id of :pid for the user with id of :id

The above README is a good start point, but a more complete documentation would be better. You can consider some libraries to generate documentation like Google APIs Discovery Service, apiDoc or Swagger.

Setup

We define our composer.json with our project information and dependencies:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
    "name": "yourname/users-management",
    "description": "Simple RESTful API for users management",
    "license": "MIT",
    "authors": [
        {
            "name": "Your Name",
            "email": "you@yourdomain.com"
        }
    ],
    "require": {
        "slim/slim": "*",
        "slim/extras": "*",
        "slim/middleware": "*",
        "monolog/monolog": "*",
        "j4mie/paris": "*",
        "flynsarmy/slim-monolog": "*"
    },
    "archive": {
        "exclude": ["vendor", ".DS_Store", "*.log"]
    },
    "autoload": {
        "psr-0": {
            "API": "lib/"
        }
    }
}

As we can see in our composer.json, along with Slim we’re using Paris (lightweight Active Record implementation on top of Idiorm) to access the database layer and Monolog for logging.

Bootstrap our API

The bootstrap.php file is in charge to autoload classes and load configurations.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Init application mode
if (empty($_ENV['SLIM_MODE'])) {
    $_ENV['SLIM_MODE'] = (getenv('SLIM_MODE'))? getenv('SLIM_MODE') : 'dev';
}

// Init and load configuration
$config = array();
$configFile = dirname(__FILE__) . '/config/config.'. $_ENV['SLIM_MODE'] . '.php';

if (is_readable($configFile)) {
    require_once $configFile;
} else {
    require_once dirname(__FILE__) . '/config/config.default.php';
}

// Create App
$app = new API\Application($config['app']);

// Get log writer
$log = $app->getLog();

// Init database
try {
    if (!empty($config['db'])) {
        \ORM::configure($config['db']['dsn']);
        if (!empty($config['db']['username'])
            && !empty($config['db']['password'])) {
            \ORM::configure('username', $config['db']['username']);
            \ORM::configure('password', $config['db']['password']);
        }
    }
} catch (\PDOException $e) {
    $log->error($e->getMessage());
}

// Add some Middlewares here (we discuss about this later)

First, we get the environment we are using (could be dev, staging, prod or whatever you want and define) and then we load the environment related configuration, it there is not, we load default configuration. Then we create the application which as you can see it’s an Application class which extends the basic Slim class; and at the end we try to connect to the database.

Later we will add some Middleware to our app, you can read about what a Middleware is here.

Front Controller

Our front controller index.php is the unique entry point to our API and it’s where the magic happens. Here we’ll define the HTTP verbs to interact with our API and be able to list/create/edit/delete our “Users” and “Phonenumbers“.

Here is our front controller where we’ll start writing our methods (HTTP verbs):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
require_once dirname(__FILE__) . '/bootstrap.php';

// API group
$app->group('/api', function () use ($app, $log) {

    // Version group
    $app->group('/v1', function () use ($app, $log) {

        // GET route for all users
        $app->get('/users', function () use ($app, $log) {
            // Some code here
        });

        // GET route
        $app->get('/users/:id', function ($id) use ($app, $log) {
            // Some code here
        });

        // POST route, for creating
        $app->post('/users', function () use ($app, $log) {
            // Some code here
        });

        // PUT route, for updating
        $app->put('/users/:id', function ($id) use ($app, $log) {
            // Some code here
        });

        // DELETE route
        $app->delete('/users/:id', function ($id) use ($app, $log) {
            // Some code here
        });


        // GET route for all users's phonenumbers
        $app->get('/users/:id/phonenumbers', function ($id) use ($app, $log) {
            // Some code here
        });

        // GET route for specific user's phonenumber
        $app->get('/users/:id/phonenumbers/:pid', function ($id, $phoneId) use ($app, $log) {
            // Some code here
        });

        // POST route, for creating a new user's phonenumber
        $app->post('/users/:id/phonenumbers', function ($id) use ($app, $log) {
            // Some code here
        });

        // PUT route, for updating a user's phonenumber
        $app->put('/users/:id/phonenumbers/:pid', function ($id, $phoneId) use ($app, $log) {
            // Some code here
        });

        // DELETE route, for delete a user's phonenumber
        $app->delete('/users/:id/phonenumbers/:pid', function ($id, $phoneId) use ($app, $log) {
            // Some code here
        });
    });
});

We’ve created two nested groups, /api and /v1, so we can easily adhere to the “versioning in the URL” best practice to versioning APIs.

So far we’ve installed needed libraries, bootstrapped the app and defined the routes for all the end points our API will have. In the next parts of this post series we will add the logic for every method we’ve defined and we’ll add and write some Middlewares to make a fully functional API.

Keep in touch! 😀

My favorite stack

By emiviada in Symfony, Web Development 0 Comment

As I posted in an earlier post Javascript is conquering the world and in this post I want to share what is my favorite stack for building web applications.

For the latest apps I’m working I really like the following stack:

Symfony for the backend, basically the administrator interface.
AngularJS for the frontend and UI.
A RESTful API to be consumed by the frontend.

As I’m working with Symfony for a long time I decided to build my backend and administrator based on this PHP framework. For that I use a bundle I’ve written nammed HasheadoAdminBundle, but also I’m playing and experimenting with this EasyAdminBundle written by Javier Eguiluz.

For the frontend I’m using AngularJS, a really cool framework to extend HTML and build rich web applications. There is really good documentation to learn Angular in its own website and it also has a great community.

To build the RESTful API I’m using great Symfony bundles like FOSRestBundle and the JMSSerializerBundle. Here there is a really cool post to see how to build a cool API.

Well, I hope this post help you.

Migrate ElasticSearch data from one server to another one

By emiviada in Monitoring, Web Development 2 Comments

As part of the logging system in a big project I’m working for a long time ago we are using Graylog to storage the logs coming from the application as well as from devices and services.

As you may know Graylog uses ElasticSearch to store the data (logs) and MongoDB to store some metadata and configuration.

For these days we are facing the need to grow our stack and make our logging system more scalable, and also, with the release of Graylog 1.0.1 we decided to build a new and more powerful logging system. Said that, and keeping on mind that we have to maintain the already existing logs, we faced the problem to migrate those existing logs (data) into the new ElasticSeach instance.

After some research on existing tools to do that, we found Elasticsearch-Exporter.

To install Elasticsearch-Exporter:

1
2
3
user@unix:~$ npm install nomnom
user@unix:~$ npm install colors
user@unix:~$ npm install elasticsearch-exporter --production

Then to copy all indices from server A to server B:

1
user@unix:~$ node exporter.js -a serverA -b serverB

After letting it run for a while, we start seeing messages like:

1
Processed 4144396 of 10626656 entries (39%)

And that’s. After the process finished we have the existing data in the new Server B. Enjoy it! 😀

The Future of Web Development

By emiviada in Javascript, PHP, Thoughts, Web Development 1 Comment

Past, present and future of web development based on my own experience.

The web development work is something that I really love it and enjoy working on it, and as a full-stack web developer who is working on this from the last 8 years I want to share my experiences and thoughts about it.

I am mainly a PHP developer but I think these thoughts can apply to others backend languages like ASP or JAVA. When I started developing web apps with PHP it really was at your own way, writing spaghetti code and having PHP and HTML mixed, and honestly I think PHP was a little immature but for that time it just worked.

Fortunately, PHP has grown a lot as well as its community and in nowadays we have really great frameworks like Symfony, Zend, Laravel or much more, so if you are developing web applications my advise is please use a framework.

Javascript is conquering the world. Javascript exists from the almost the beginning of the Internet and it was and it is used for client-side functionalities, but in the last years is evolving so much until reached server-side development with nodejs. This made me think, why we need to have one server-side language and another client-side language? when we can have a developed application fully by the same language (in this case Javascript). Also, Javascript has evolved a lot in the client-side with great frameworks like BackboneJS, AngularJS or EmberJS, so if you are interesting on them, please take a look on them.

Web development and mobile development are siblings, when you are developing web apps you should think on make them mobile compatible. Nowadays, more than 25% of website visits are originated from mobile devices and it is expected to be the 50% in 2017. So, for that you need to think making your apps mobile friendly.

A great trend is which allow us to use a web app that acts like a desktop application updating only the needed views instead of reloading entire pages every time the user navigates between sections. Great frameworks to build websites like this are the already mentioned BackboneJS, AngularJs or EmberJS. Also, I would like to mention a promising full-stack Javascript framework like MEAN.

In conclusion I think the web development future is full-stack javascript and SPA applications, using nodejs in server-side development and one of the great JS frameworks mentioned above in the client-side development, or at least building these applications consuming APIs or web services built them with a mature PHP framework (Symfony in my preference :-)).

Please, keep learning, reading, hearing about web development, it is something amazing.