Tutorial
Building a RESTful web API using Expressive

by Enrico Zimuel
Senior Software Engineer
Rogue Wave Software (USA)

ZendCon & OpenEnterprise, Las Vegas (NV), Oct 15, 2018

About me

Web APIs

HTTP IN & OUT

Example

HTTP Request:


GET /api/version

HTTP Response:


HTTP/1.1 200 OK
Connection: close
Content-Length: 17
Content-Type: application/json

{
  "version": "1.0"
}

Building a Web API

  • Managing the HTTP request and response
  • Choosing a representation format
  • Choosing an error format
  • Filtering & validating input data
  • Authenticating HTTP requests
  • Authorizing HTTP requests
  • Documentation

HTTP Methods (REST approach)

  • GET: read a resource
  • HEAD: read without body
  • POST: create a resource
  • PUT: replace a resource
  • PATCH: update a resource
  • DELETE: delete a resource
  • OPTIONS: information about a resource

HTTP Status-code

  • Informational 1xx: 100 Continue
  • Successful 2xx: 200 OK, 201 Created, 202 Accepted
  • Redirection 3xx: 301 Moved Permanently, 307 Temporary Redirect
  • Client Error 4xx: 401 Unauthorized, 404 Not Found, 405 Method Not Allowed
  • Server Error 5xx: 500 Internal Server Error, 503 Service Unavailable

Representation format

  • JSON (JavaScript Object Notation)
    in PHP json_encode(), json_decode()
  • XML (eXtensible Markup Language)
    in PHP SimpleXML, libxml, DOM, etc

HAL-JSON

HAL-JSON (Hypertext Application Language JSON), Internet-Draft


GET /api/user/ezimuel
{
    "_links": {
        "self": {
            "href": "http://domain/api/user/ezimuel"
        },
        "contacts": [
            { "href": "http://domain/api/user/mwop" },
            { "href": "http://domain/api/user/zeevs" }
        ]
    },
    "id": "ezimuel",
    "name": "Enrico Zimuel"
}

Error format

Problem Details (RFC 7807)


HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
    "type": "https://example.net/validation-error",
    "title": "Your request parameters didn't validate.",
    "invalid-params": [
        {
            "name": "age",
            "reason": "must be a positive integer"
        },
    ]
}

Authentication

Documentation

HTTP in PHP

HTTP message in PHP

Global variables:

  • $_SERVER
  • $_POST
  • $_GET
  • $_FILES
  • $_COOKIE

HTTP functions in PHP

  • http_response_code()
  • header(), header_remove(), headers_list(), headers_sent()
  • setcookie(), setrawcookie()
  • gethostname(), etc

Manage HTTP in PHP

  • PHP does not offer an object representation of HTTP request/response
  • Unfortunately, It's quite hard to manage HTTP messages in PHP!

PHP-FIG

PHP FIG

  • PHP Framework Interop Group (PHP FIG)
  • A working group for defining common standards to interop between PHP frameworks/libraries
  • PHP Standards Recommendations (PSR)
  • More information at php-fig.org

PSR-7

Common interfaces for representing HTTP messages as described in RFC 7230 and RFC 7231, and URIs for use with HTTP messages as described in RFC 3986

PSR-7 interfaces

  • github: psr/http-message
  • Psr\Http\Message\MessageInterface
  • Psr\Http\Message\RequestInterface
  • Psr\Http\Message\ResponseInterface
  • Psr\Http\Message\ServerRequestInterface
  • Psr\Http\Message\StreamInterface
  • Psr\Http\Message\UploadedFileInterface
  • Psr\Http\Message\UriInterface

Example


// Returns an empty array if not found:
$header = $message->getHeader('Accept');
// Returns an empty string if not found:
$header = $message->getHeaderLine('Accept');
// Test for a header:
if (! $message->hasHeader('Accept')) {
}
// If the header has multiple values, fetch them
// as an array:
$values = $message->getHeader('X-Foo');
// Or as a comma-separated string:
$values = $message->getHeaderLine('X-Foo');

Immutability

  • PSR-7 Request and Response model immutability
  • Messages are modeled as value objects; a change to any value results in a new instance
  • PSR-7 Stream does not model immutability

zendframework/zend-diactoros implements PSR-7

Example


$response = $response->withStatus(418, "I'm a teapot");

$query   = $request->getQueryParams();
$body    = $request->getBodyParams();

$request = $request->withBodyParams(json_decode($body));

Middleware

Middleware

A function that gets a request and generates a response


function ($request)
{
    // do something with $request
    return $response;
}

Delegating middleware


function ($request, callable $delegate)
{
    // delegating $request to another middleware
    $response = $delegate($request);
    return $response;
}

Middleware onion

Execution pipeline

Example: cache


function ($request, callable $delegate) use ($cache)
{
    if ($cache->has($request)) {
        return $cache->get($request);
    }
    $response = $delegate($request);
    $cache->set($request, $response);
    return $response;
}

PSR-15

Common interfaces for HTTP server request handlers and HTTP server middleware components that use HTTP messages as described by PSR-7

PSR-15: Handler


namespace Psr\Http\Server;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

interface RequestHandlerInterface
{
    public function handle(
        ServerRequestInterface $request
    ): ResponseInterface;
}

An handler returns a response, without delegate

PSR-15: Middleware


namespace Psr\Http\Server;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

interface MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;
}

A middleware participates in processing an HTTP message, it may deletegate.

Expressive

The PHP framework for middleware applications

Installation

You can install Expressive using composer:

composer create-project zendframework/zend-expressive-skeleton api

Routes


$app->get('/api/ping', function ($request) {
    return JsonResponse(['ack' => time()])
});

// or implement a RequestHandlerInterface
$app->get('/api/ping', App\Handler\PingHandler::class);

PingHandler


namespace App\Handler;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Zend\Diactoros\Response\JsonResponse;

class PingHandler implements RequestHandlerInterface
{
    public function handle(
        ServerRequestInterface $request
    ) : ResponseInterface {
        return new JsonResponse(['ack' => time()]);
    }
}

Pipeline


$app->pipe(ErrorHandler::class);
$app->pipe(ServerUrlMiddleware::class);
$app->pipe(RouteMiddleware::class);
$app->pipe(ImplicitHeadMiddleware::class);
$app->pipe(ImplicitOptionsMiddleware::class);
$app->pipe(MethodNotAllowedMiddleware::class);
$app->pipe(UrlHelperMiddleware::class);
$app->pipe(ProblemDetailsMiddleware::class);
$app->pipe(DispatchMiddleware::class);
$app->pipe(NotFoundHandler::class);
/config/pipeline.php

Route a REST API


$app->route('/api/users[/{id}]', [
    Authentication\AuthenticationMiddleware::class,
    Authorization\AuthorizationMiddleware::class,
    Api\Action\UserAction::class
], ['GET', 'POST', 'PATCH', 'DELETE'], 'api.users');

// or route each HTTP method
$app->get('/api/users[/{id}]', ..., 'api.users.get');
$app->post('/api/users', ..., 'api.users.post');
$app->patch('/api/users/{id}', ..., 'api.users.patch');
$app->delete('/api/users/{id}', ..., 'api.users.delete');

Tools for Web API

Hands-on

github.com/ezimuel/zend-expressive-api

Thanks!

More info: http://getexpressive.org

Contact me: enrico.zimuel [at] roguewave.com

Follow me: @ezimuel



Creative Commons License
This work is licensed under a
Creative Commons Attribution-ShareAlike 3.0 Unported License.
I used reveal.js to make this presentation.