Building Modern APIs with Slim Framework Rob Allen, February 2020 Rob Allen ~ @akrabat

Today’s plan • Learn a bit about Slim for context • Learn the features of a good API • Put them into practice within a Slim application • Coffee & cake! Rob Allen ~ @akrabat

What do you know about APIs? Rob Allen ~ @akrabat

Rock-Paper-Scissors An API to play Rock-Paper-Scissors 1. Create a new game 2. Make first player’s move 3. Make second player’s move 4. Get result Rob Allen ~ @akrabat

Create a game $ curl -H “Content-Type: application/json” \ http://localhost:8888/games \ -d ‘{“player1”: “Rob”, “player2”: “Jon”}’ Rob Allen ~ @akrabat

Create a game $ curl -H “Content-Type: application/json” \ http://localhost:8888/games \ -d ‘{“player1”: “Rob”, “player2”: “Jon”}’ { “_links”: { “makeNextMove”: { “href”: “/games/2ab83e2a-98d0-4110-b3ae-90d6fbf5/moves”, “description”: “Make a player’s move” } } } Rob Allen ~ @akrabat

Make a move $ curl -H “Content-Type: application/json” \ http://localhost:8888/games/2ab83e2a-98d0-4110-b3ae-90d6fbf5/moves -d ‘{“player”: “Rob”, “move”: “rock”}’ Rob Allen ~ @akrabat

Make a move $ curl -H “Content-Type: application/json” \ http://localhost:8888/games/2ab83e2a-98d0-4110-b3ae-90d6fbf5/moves -d ‘{“player”: “Rob”, “move”: “rock”}’ { “_links”: { “makeNextMove”: { “href”: “/games/2ab83e2a-98d0-4110-b3ae-90d6fbf5/moves”, “description”: “Make player 2’s move” } } } Rob Allen ~ @akrabat

Make other move $ curl -H “Content-Type: application/json” \ http://localhost:8888/games/2ab83e2a-98d0-4110-b3ae-90d6fbf5/moves -d ‘{“player”: “Jon”, “move”: “rock”}’ Rob Allen ~ @akrabat

Make other move $ curl -H “Content-Type: application/json” \ http://localhost:8888/games/2ab83e2a-98d0-4110-b3ae-90d6fbf5/moves -d ‘{“player”: “Jon”, “move”: “rock”}’ { “result”: “Draw. Both players chose rock”, “_links”: { “newGame”: { “href”: “/games/”, “description”: “Start a new game” } } } Rob Allen ~ @akrabat

Slim The C in MVC Rob Allen ~ @akrabat

Slim Framework • Created by Josh Lockhart (phptherightway.com) • PSR-4 autoloading • PSR-7 Request and Response objects • PSR-15 Middleware and Request Handlers • PSR-11 DI container support Rob Allen ~ @akrabat

Bring your own components Slim provides the router and dispatcher: You provide: • PSR-7 component • PSR-11 DI container • View layer (templates) • Model layer (Database/ORM) Rob Allen ~ @akrabat

Getting started $ composer create-project akrabat/slim4-starter hello-api Slim4-Starter provides: • Slim 4 • Slim-Psr7 • PHP-DI • Monolog Rob Allen ~ @akrabat

Getting started Start a web server $ php -S 0.0.0.0:8888 -t public/ PHP 7.4.2 Development Server (http://0.0.0.0:8888) started Rob Allen ~ @akrabat

Getting started Rob Allen ~ @akrabat

Getting started Rob Allen ~ @akrabat

Directory structure ├── │ │ │ │ ├── │ ├── │ │ config/ ├── dependencies.php ├── middleware.php ├── routes.php └── settings.php public/ └── index.php src/ └── Handler/ └── HomePageHandler.php ├── │ │ ├── ├── └── var/ ├── cache/ └── log/ vendor/ composer.json composer.lock Rob Allen ~ @akrabat

How does Slim work? 1. Bootstrap application 2. Execute routing 3. Dispatch route handler 4. Return response Rob Allen ~ @akrabat

Routing 1. Inspect URL and matches segments 2. On match: • Add Route object to Request attribute (route) • Dispatch associated route handler Rob Allen ~ @akrabat

Route handlers • Manage business logic operations • Receive a PSR-7 ServerRequest • Return a PSR-7 Response • Implemented as PSR-15 RequestHandler Rob Allen ~ @akrabat

HomePageHandler class HomePageHandler implements RequestHandlerInterface { public function process( ServerRequestInterface $request, ) : ResponseInterface { $response = new Response(); $response->getBody()->write(“Hello $name”); } } Rob Allen ~ @akrabat

Coding time Create a Slim app Rob Allen ~ @akrabat

HTTP is the foundation Rob Allen ~ @akrabat

It’s all about HTTP HTTP is a stateless request/response protocol that operates by exchanging messages. RFC 7230 Rob Allen ~ @akrabat

Client request POST /v2.1/events/18/comments HTTP/1.1 Host: api.dev.joind.in User-Agent: curl/7.54.0 Accept: application/xml; q=0.8, application/json Content-Type: application/json Content-Length: 59 {“comment”:”Great Talk. Nothing wrong with it!”,”rating”:5} Rob Allen ~ @akrabat

Server response HTTP/1.1 401 Unauthorized Server: Apache/2.2.22 (Debian) Status: 400 Content-Length: 32 Connection: close Content-Type: application/json; charset=utf8 [“Invalid Authorization Header”] Rob Allen ~ @akrabat

PSR-7 OO interfaces to model HTTP • RequestInterface (& ServerRequestInterface) • ResponseInterface • UriInterface • UploadedFileInterface Rob Allen ~ @akrabat

Key feature 1: Immutability Request, Response, Uri & UploadFile are immutable $uri = new Uri(‘https://api.joind.in/v2.1/events’); $uri2 = $uri->withQuery(‘?filter=upcoming’); $uri3 = $uri->withQuery(‘?filter=cfp’); with() methods return a new object with the new information Rob Allen ~ @akrabat

Key feature 1: Immutability // This does not work $response = new Response(); $response->withStatus(200); $response->withHeader(‘Content-type’, ‘text/xml’); Rob Allen ~ @akrabat

Key feature 1: Immutability // This does not work $response = new Response(); $response->withStatus(200); $response->withHeader(‘Content-type’, ‘text/xml’); // This works: Reassign returned object $response = new Response(); $response = $response->withStatus(200); $response = $response->withHeader(‘Content-type’, ‘text/xml’); Rob Allen ~ @akrabat

Key feature 2: Streams Message bodies are streams $body = new Stream(); $body->write(‘<p>Hello’); $body->write(‘World</p>’); $response = (new Response()) ->withStatus(200, ‘OK’) ->withHeader(‘Content-Type’, ‘text/html’) ->withBody($body); Rob Allen ~ @akrabat

Let’s talk APIs Rob Allen ~ @akrabat

Features of a good API • Correctness • Malleability • Error handling • Documentation Rob Allen ~ @akrabat

tl;dr Ensure your API is maintainable and developer-friendly

Get it right! Rob Allen ~ @akrabat

Embrace HTTP methods Method GET PUT DELETE POST PATCH Used for Retrieve data Change data Delete data Change data Update data Idempotent? Yes Yes Yes No No (HTTP methods are also known as verbs) Rob Allen ~ @akrabat

HTTP method negotiation If a given resource (URI) doesn’t support the requested HTTP verb, then return: 405 Method Not Allowed Rob Allen ~ @akrabat

HTTP method negotiation If a given resource (URI) doesn’t support the requested HTTP verb, then return: 405 Method Not Allowed $ curl -i -X PUT -H “Accept: application/json” http://localhost:8888 HTTP/1.1 405 Method Not Allowed Allow: GET Content-type: application/json { “message”: “405 Method Not Allowed”, } Rob Allen ~ @akrabat

URLs matter • Be consistent • Prefer nouns for resource names • Plural names work best for collections • Unique URL for each resource (/users/123) • Resources can be named after business processes too (e.g. customer-enrolment, money-transfer, merges) Rob Allen ~ @akrabat

Status codes Send the right one for the right situation! 1xx 2xx 3xx 4xx 5xx Informational Success Redirection Client error Server error (We’re still working) (All done) (Go elsewhere) (Your fault) (Our fault) Rob Allen ~ @akrabat

Rock-Paper-Scissors Verb URL GET POST GET POST /games /games /games/123 /games/123/moves Purpose List all games Start a new game Find out about game 123 Play a move in game 123 Rob Allen ~ @akrabat

Routing Uris in Slim config/routes.php: $app->get( ‘/games’, App\Handler\ListGames::class )->setName(‘games’); Rob Allen ~ @akrabat

Routes have a method config/routes.php: $app->get( ‘/games’, App\Handler\ListGames::class )->setName(‘games’); // Method Rob Allen ~ @akrabat

$app method => HTTP verb $app->get() $app->post() $app->put() $app->patch() $app->delete() Multiple methods: $app->any() $app->map([‘GET’, ‘POST’], …); Rob Allen ~ @akrabat

Routes have a pattern config/routes.php: $app->get( ‘/games’, App\Handler\ListGames::class )->setName(‘games’); // Patten Rob Allen ~ @akrabat

Route pattern // literal $app->get(‘/games’, $handler); // placeholder within { & } (access as request attribute) $app->get(‘/games/{id}’, $handler); // constrain using regex $app->get(‘/games/{id:\d+}’, $handler); // optional segments use [ & ] $app->get(‘/games[/{id:\d+}]’, $handler); $app->get(‘/news[/{y:\d{4}}[/{m:\d{2}}]]’, $handler); Rob Allen ~ @akrabat

Routes have a handler config/routes.php: $app->get( ‘/games’, App\Handler\ListGames::class )->setName(‘games’); // Handler Rob Allen ~ @akrabat

Route handlers • Manage business logic operations • Receive a PSR-7 ServerRequest • Return a PSR-7 Response • Implemented as PSR-15 RequestHandler Rob Allen ~ @akrabat

Responses in Slim Create a new Response object and use the with methods: $response = new Response(); // status code $response = $response->withStatus(404); // headers $response = $response->withHeader(‘Content-Type’,’application/json’); // body $response->getBody()->write(json_encode([‘foo’ => ‘bar’]))); Rob Allen ~ @akrabat

Coding time Handlers Rob Allen ~ @akrabat

Incoming data Rob Allen ~ @akrabat

Content-Type handling The Content-Type header specifies the format of the incoming data $ curl http://localhost:8888/games \ -H “Content-Type: application/json” \ -d ‘{“player1”: “Rob”, “player2”: “Jon”}’ Rob Allen ~ @akrabat

Read with getBody() $app->post(‘/games’, function ($request, $response) { $data = $request->getBody(); $response->getBody()->write(print_r($data, true)); return $response; } ); Output is a string: ‘{“player1”: “Rob”, “player2”: “Jon”}’ Rob Allen ~ @akrabat

Read with getParsedBody() Add Slim’s body-parsing middleware to your app: $app->addBodyParsingMiddleware(); Use in your handler: $app->post(‘/games’, function ($request, $response) { $data = $request->getParsedBody(); return $response->write(print_r($data, true)); } ); Rob Allen ~ @akrabat

Read with getParsedBody() $ curl -H “Content-Type: application/json” \ -H “Content-Type: application/json” \ -d ‘{“player1”: “Rob”, “player2”: “Jon”}’ Output is an array: Array ( [player1] => Rob, [player2] => Jon ) Rob Allen ~ @akrabat

This also works with XML $ curl “http://localhost:8888/games” \ -H “Content-Type: application/xml” \ -d “<game><player1>Rob</player1><player2>Jon</player2></game>” Output: Array ( [player1] => Rob, [player2] => Jon ) Rob Allen ~ @akrabat

And form data curl “http://localhost:8888/games” \ -H “Content-Type: application/x-www-form-urlencoded” \ -d “player1=Rob’ -d ‘player2=Jon” Output: Array ( [player1] => Rob, [player2] => Jon ) Rob Allen ~ @akrabat

addBodyParsingMiddleware() ? Rob Allen ~ @akrabat

Middleware Middleware is code that exists between the request and response, and which can take the incoming request, perform actions based on it, and either complete the response or pass delegation on to the next middleware in the queue. Matthew Weier O’Phinney Rob Allen ~ @akrabat

Middleware Take a request, return a response Rob Allen ~ @akrabat

Middleware LIFO stack: $app->add(ValidationMiddleware::class); $app->add(AuthMiddleware::class); $app->add(AuthMiddleware::class); $app->addBodyParsingMiddleware(); $app->addErrorMiddleware(true, true, true); Rob Allen ~ @akrabat

PSR-15 MiddlewareInterface namespace Psr\Http\Server; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; interface MiddlewareInterface { public function process( ServerRequestInterface $request, RequestHandlerInterface $handler ) : ResponseInterface; } Rob Allen ~ @akrabat

PSR-15 MiddlewareInterface namespace Psr\Http\Server; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; interface MiddlewareInterface { public function process( ServerRequestInterface $request, RequestHandlerInterface $handler ) : ResponseInterface; } Rob Allen ~ @akrabat

PSR-15 MiddlewareInterface namespace Psr\Http\Server; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; interface MiddlewareInterface { public function process( ServerRequestInterface $request, RequestHandlerInterface $handler ) : ResponseInterface; } Rob Allen ~ @akrabat

PSR-15 MiddlewareInterface namespace Psr\Http\Server; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; interface MiddlewareInterface { public function process( ServerRequestInterface $request, RequestHandlerInterface $handler ) : ResponseInterface; } Rob Allen ~ @akrabat

TimerMiddleware class TimerMiddleware implements MiddlewareInterface { public function process($request, $handler) { $start = microtime(true); $response = $handler->handle($request); $taken = microtime(true) - $start; return $response->withHeader(‘Time-Taken’, $taken); } } Rob Allen ~ @akrabat

TimerMiddleware class TimerMiddleware implements MiddlewareInterface { public function process($request, $handler) { $start = microtime(true); $response = $handler->handle($request); $taken = microtime(true) - $start; return $response->withHeader(‘Time-Taken’, $taken); } } Rob Allen ~ @akrabat

TimerMiddleware class TimerMiddleware implements MiddlewareInterface { public function process($request, $handler) { $start = microtime(true); $response = $handler->handle($request); $taken = microtime(true) - $start; return $response->withHeader(‘Time-Taken’, $taken); } } Rob Allen ~ @akrabat

TimerMiddleware class TimerMiddleware implements MiddlewareInterface { public function process($request, $handler) { $start = microtime(true); $response = $handler->handle($request); $taken = microtime(true) - $start; return $response->withHeader(‘Time-Taken’, $taken); } } Rob Allen ~ @akrabat

TimerMiddleware class TimerMiddleware implements MiddlewareInterface { public function process($request, $handler) { $start = microtime(true); $response = $handler->handle($request); $taken = microtime(true) - $start; return $response->withHeader(‘Time-Taken’, $taken); } } Rob Allen ~ @akrabat

Route Handlers The other half of PSR-15! Rob Allen ~ @akrabat

Route Handlers Any callable! $app->add(‘/’, $app->add(‘/’, $app->add(‘/’, $app->add(‘/’, $app->add(‘/’, function ($request, $response) { … }); [‘RootController’, ‘aStaticFunction’]); [new RootController(), ‘aFunction’]); RootController::class.’:pingAction’); RootHander::class); Rob Allen ~ @akrabat

Use the PSR-15 one $app->add(‘/’, RootHandler::class); Rob Allen ~ @akrabat

PSR-15 RouteHandlerInterface namespace Psr\Http\Server; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; interface RequestHandlerInterface { public function handle( ServerRequestInterface $request ): ResponseInterface; } Rob Allen ~ @akrabat

PSR-15 RouteHandlerInterface namespace Psr\Http\Server; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; interface RequestHandlerInterface { public function handle( ServerRequestInterface $request ): ResponseInterface; } Rob Allen ~ @akrabat

PSR-15 RouteHandlerInterface namespace Psr\Http\Server; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; interface RequestHandlerInterface { public function handle( ServerRequestInterface $request ): ResponseInterface; } Rob Allen ~ @akrabat

PSR-15 RouteHandlerInterface namespace Psr\Http\Server; use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; interface RequestHandlerInterface { public function handle( ServerRequestInterface $request ): ResponseInterface; } Rob Allen ~ @akrabat

HomePageHandler use use use use Psr\Http\Message\ResponseInterface; Psr\Http\Message\ServerRequestInterface as Request; Psr\Http\Server\RequestHandlerInterface; Slim\Psr7\Response; class HomePageHandler implements RequestHandlerInterface { public function handle(Request $request): ResponseInterface { $response = new Response(); $response->getBody()->write(‘Hello World’); return $response; } } Rob Allen ~ @akrabat

HomePageHandler use use use use Psr\Http\Message\ResponseInterface; Psr\Http\Message\ServerRequestInterface as Request; Psr\Http\Server\RequestHandlerInterface; Slim\Psr7\Response; class HomePageHandler implements RequestHandlerInterface { public function handle(Request $request): ResponseInterface { $response = new Response(); $response->getBody()->write(‘Hello World’); return $response; } } Rob Allen ~ @akrabat

HomePageHandler use use use use Psr\Http\Message\ResponseInterface; Psr\Http\Message\ServerRequestInterface as Request; Psr\Http\Server\RequestHandlerInterface; Slim\Psr7\Response; class HomePageHandler implements RequestHandlerInterface { public function handle(Request $request): ResponseInterface { $response = new Response(); $response->getBody()->write(‘Hello World’); return $response; } } Rob Allen ~ @akrabat

HomePageHandler use use use use Psr\Http\Message\ResponseInterface; Psr\Http\Message\ServerRequestInterface as Request; Psr\Http\Server\RequestHandlerInterface; Slim\Psr7\Response; class HomePageHandler implements RequestHandlerInterface { public function handle(Request $request): ResponseInterface { $response = new Response(); $response->getBody()->write(‘Hello World’); return $response; } } Rob Allen ~ @akrabat

Coding time Reading data Rob Allen ~ @akrabat

Malleability Rob Allen ~ @akrabat

Decouple your representation Rob Allen ~ @akrabat

Hypermedia • Media type used for a representation • Links relationships between representations and states • Decouples client from server • Rename endpoints at will • Re-home endpoints on different domains Rob Allen ~ @akrabat

JSON and Hypermedia JSON does not have a defined way of providing hypermedia links Options: • “Link” header (GitHub approach) • application/collection+json • application/hal+json Rob Allen ~ @akrabat

Hypermedia payloads • Links should be fully qualified • Always include self relation • Add links to other related resources & collections Rob Allen ~ @akrabat

application/hal+json http://stateless.co/hal_specification.html { “_links”: { “self”: { “href”: “https://example.com/orders/523” }, “warehouse”: { “href”: “https://example.com/warehouse/56” }, “invoice”: { “href”: “https://example.com/invoices/873” } }, “currency”: “GBP”, “status”: “shipped”, “total”: 123.45 } Rob Allen ~ @akrabat

Base URL in Slim class BaseUrlMiddleware implements MiddlewareInterface { public function process($request, $handler) { $uri = $request->getUri(); $scheme = $uri->getScheme(); $authority = $uri->getAuthority(); $rootUrl = ($scheme !== ” ? $scheme . ‘:’ : ”) . ($authority !== ” ? ‘//’ . $authority : ”); $request = $request->withAttribute(‘base_url’, $rootUrl); return $handler->handle($request); Rob Allen ~ @akrabat

Creating links public function handle(ServerRequestInterface $request) { $baseUrl = $request->getAttribute(‘base_url’); $listGamesUrl = $baseUrl . ‘/games’; $gameUrl = $baseUrl . ‘/games/’ . $id; // … Rob Allen ~ @akrabat

HAL payloads: collection $hal = new Hal($baseUrl . ‘/games’); foreach ($games as $game) { $data[‘player1’] = $game->player1(); $data[‘player2’] = $game->player2(); //… $self = $baseUrl . ‘/games/’ . $game->id; $resource = new Hal($self, $data); $hal->addResource(‘game’, $resource); } $hal->setData([‘count’ => count($games)]); $json = $hal->asJson(true); Rob Allen ~ @akrabat

HAL output $ curl http://localhost:8888/games/0a1846ab-df37-4f7b-8e42-c0ef3ec { “player1”: “Rob”, “player2”: “Jon”, “status”: “Game complete”, “created”: “2019-09-30 08:49:33”, “result”: “Rob wins. rock beats scissors.”, “winner”: “Rob”, “_links”: { … } } Rob Allen ~ @akrabat

HAL links { … “winner”: “Rob”, “_links”: { “self”: { “href”: “http://localhost:8888/games/0a1846ab-df37-4f7b-8e42… }, “newGame”: { “href”: “http://localhost:8888/games/”, “description”: “Start a new game” } } } Rob Allen ~ @akrabat

Pagination Mobile devices don’t that much memory! • Link relations: first, last, next & prev relations • Include total count of items too Rob Allen ~ @akrabat

Coding time Hypermedia Rob Allen ~ @akrabat

Error handling Rob Allen ~ @akrabat

Error handling • Internal logging of errors for ourselves • Error representations are first class citizens • Code for computers, messages for humans Rob Allen ~ @akrabat

Injecting a logger More PSRs! 11 & 3 Rob Allen ~ @akrabat

Configure PHP-DI $containerBuilder = new ContainerBuilder(); $containerBuilder->addDefinitions([ // Factory for a PSR-3 logger LoggerInterface::class => function (ContainerInterface $c) { $logger = new Logger($settings[‘name’]); $logger->pushHandler(new ErrorLogHandler()); return $logger; }, ]); AppFactory::setContainer($containerBuilder->build()); $app = AppFactory::create(); Rob Allen ~ @akrabat

Configure PHP-DI $containerBuilder = new ContainerBuilder(); $containerBuilder->addDefinitions([ // Factory for a PSR-3 logger LoggerInterface::class => function (ContainerInterface $c) { $logger = new Logger($settings[‘name’]); $logger->pushHandler(new ErrorLogHandler()); return $logger; }, ]); AppFactory::setContainer($containerBuilder->build()); $app = AppFactory::create(); Rob Allen ~ @akrabat

Configure PHP-DI $containerBuilder = new ContainerBuilder(); $containerBuilder->addDefinitions([ // Factory for a PSR-3 logger LoggerInterface::class => function (ContainerInterface $c) { $logger = new Logger($settings[‘name’]); $logger->pushHandler(new ErrorLogHandler()); return $logger; }, ]); AppFactory::setContainer($containerBuilder->build()); $app = AppFactory::create(); Rob Allen ~ @akrabat

Configure PHP-DI $containerBuilder = new ContainerBuilder(); $containerBuilder->addDefinitions([ // Factory for a PSR-3 logger LoggerInterface::class => function (ContainerInterface $c) { $logger = new Logger($settings[‘name’]); $logger->pushHandler(new ErrorLogHandler()); return $logger; }, ]); AppFactory::setContainer($containerBuilder->build()); $app = AppFactory::create(); Rob Allen ~ @akrabat

Configure PHP-DI $containerBuilder = new ContainerBuilder(); $containerBuilder->addDefinitions([ // Factory for a PSR-3 logger LoggerInterface::class => function (ContainerInterface $c) { $logger = new Logger($settings[‘name’]); $logger->pushHandler(new ErrorLogHandler()); return $logger; }, ]); AppFactory::setContainer($containerBuilder->build()); $app = AppFactory::create(); Rob Allen ~ @akrabat

PHP-DI autowiring Just type-hint your constructor! class GetGameHandler implements RequestHandlerInterface { private $logger; public function __construct(LoggerInterface $logger) { $this->logger = $logger; } … Rob Allen ~ @akrabat

Logging class GetGameHandler implements RequestHandlerInterface { public function handle(Request $request): ResponseInterface this->logger->info(“Fetching game”, [‘id’ => $id]); try { $games = $this->gameRepository->loadById($id); } catch (NotFoundException $e) { this->logger->info(“No game found”, [‘id’ => $id]); throw new HttpNotFoundException($request, ‘No Game’, $e); } … Rob Allen ~ @akrabat

Logging class GetGameHandler implements RequestHandlerInterface { public function handle(Request $request): ResponseInterface this->logger->info(“Fetching game”, [‘id’ => $id]); try { $games = $this->gameRepository->loadById($id); } catch (NotFoundException $e) { this->logger->info(“No game found”, [‘id’ => $id]); throw new HttpNotFoundException($request, ‘No Game’, $e); } … Rob Allen ~ @akrabat

Rendering errors Rob Allen ~ @akrabat

Slim’s error handling Add Slim’s error handling middleware to render exceptions $displayDetails = true; $logErrors = true; $logDetails = true; $app->addErrorMiddleware($displayDetails, $logErrors, $logDetails); Rob Allen ~ @akrabat

Error rendering $ http -j DELETE http://localhost:8888/game Rob Allen ~ @akrabat

Error rendering $ http -j DELETE http://localhost:8888/game HTTP/1.1 405 Method Not Allowed Allow: GET Content-type: application/json Rob Allen ~ @akrabat

Error rendering $ http -j DELETE http://localhost:8888/game HTTP/1.1 405 Method Not Allowed Allow: GET Content-type: application/json { “exception”: [ { “code”: 405, “file”: “…/Slim/Middleware/RoutingMiddleware.php”, “message”: “Method not allowed: Must be one of: GET”, “type”: “Slim\Exception\HttpMethodNotAllowedException” } ], “message”: “Method not allowed: Must be one of: GET” } Rob Allen ~ @akrabat

Convert errors to HTTP exceptions public function handle(Request $request): ResponseInterface { $id = $request->getAttribute(‘id’); try { $game = $this->gameRepository->loadById($id); } catch (GameNotFoundException $e) { throw new HttpNotFoundException($request, ‘No Game’, $e); } catch (Exception $e) { throw new HttpInternalServerErrorException($request, ‘An unknown error occurred’, $e); } Rob Allen ~ @akrabat

Not found error public function handle(Request $request): ResponseInterface { $id = $request->getAttribute(‘id’); try { $game = $this->gameRepository->loadById($id); } catch (GameNotFoundException $e) { throw new HttpNotFoundException($request, ‘No Game’, $e); } catch (Exception $e) { throw new HttpInternalServerErrorException($request, ‘An unknown error occurred’, $e); } Rob Allen ~ @akrabat

Not found error $ http -j http://localhost:8888/games/1234 HTTP/1.1 404 Not Found Content-type: application/json { “message”: “No Game” } (Production mode: $displayDetails = false) Rob Allen ~ @akrabat

Generic error public function handle(Request $request): ResponseInterface { $id = $request->getAttribute(‘id’); try { $game = $this->gameRepository->loadById($id); } catch (GameNotFoundException $e) { throw new HttpNotFoundException($request, ‘No Game’, $e); } catch (Exception $e) { throw new HttpInternalServerErrorException($request, ‘An unknown error occurred’, $e); } Rob Allen ~ @akrabat

Generic error $ http -j http://localhost:8888/games/abcd HTTP/1.1 500 Internal Server Error Content-type: application/json { “exception”: [ { “code”: 500, “file”: “…/src/Handler/GetGameHandler.php”, “line”: 43, “message”: “An unknown error occurred”, “type”: “Slim\Exception\HttpInternalServerErrorException” }, Rob Allen ~ @akrabat

{ “code”: 40, “file”: “…/lib/Assert/Assertion.php”, “line”: 2752, “message”: “Value “abcd” is not a valid integer.”, “type”: “Assert\InvalidArgumentException” } ], “message”: “An unknown error occurred” } (Development mode: $displayDetails = true) Rob Allen ~ @akrabat

Coding time Error responses Rob Allen ~ @akrabat

Documentation Rob Allen ~ @akrabat

Documentation • Tutorials • Reference Rob Allen ~ @akrabat

OpenAPI Specification • Spec-first API design • Tooling: https://openapi.tools • Reference website: ReDoc • Linting/validation: Spectral • Mock server: Prism Rob Allen ~ @akrabat

OpenAPI Specification openapi: “3.0.2” info: title: Rock-Paper-Scissors version: “1.0.0” description: An implementation of Rock-Paper-Scissors contact: name: Rob Allen servers: - url: https://rock-paper-scissors.example.com Rob Allen ~ @akrabat

OpenAPI Specification paths: /games: post: summary: Create a new game description: Create a new game of Rock-Paper-Scissors operationId: createGame tags: - Game requestBody: description: Game to add content: application/json: schema: $ref: ‘#/components/schemas/NewGameRequest’ Rob Allen ~ @akrabat

Test with prism $ npm install -g @stoplight/prism-cli $ prism mock rps-openapi.yaml › › › › [CLI] [HTTP [CLI] [CLI] … awaiting Starting Prism… SERVER] info Server listening at http://127.0.0.1:4010 info POST http://127.0.0.1:4010/games info POST http://127.0.0.1:4010/games/e3..1/moves Rob Allen ~ @akrabat

Test with prism $ curl -i -X POST http://localhost:4010/games HTTP/1.1 400 Bad Request content-type: application/json {“message”:”Must provide both player1 and player2”} Rob Allen ~ @akrabat

Test with prism $ curl -i -X POST http://localhost:4010/games HTTP/1.1 400 Bad Request content-type: application/json {“message”:”Must provide both player1 and player2”} › › › › › › › [HTTP SERVER] post /games info Request received [NEGOTIATOR] info Request contains an accept header: / [VALIDATOR] warning Request did not pass the validation rules [NEGOTIATOR] success Found response 400. [NEGOTIATOR] success The response 400 has a schema. [NEGOTIATOR] success Responding with status code 400 [VALIDATOR] error Violation: request Body parameter is required Rob Allen ~ @akrabat

Demo The RPS OpenAPI Spec Rob Allen ~ @akrabat

To sum up Rob Allen ~ @akrabat

To sum up • HTTP method negotiation • Content-type negotiation • Hypermedia • Error handling • Documentation Rob Allen ~ @akrabat

Resources • https://akrabat.com/category/api/ • https://akrabat.com/category/slim-framework/ • https://github.com/akrabat/slim4-rps-api • https://apihandyman.io • https://apievangelist.com • http://restcookbook.com Rob Allen ~ @akrabat

Thank you! Rob Allen - Independent API developer http://akrabat.com - @akrabat Rob Allen ~ @akrabat

Photo credits - The Fat Controller: HiT Entertainment - Foundation: https://www.flickr.com/photos/armchairbuilder/6196473431 - APIs: https://www.flickr.com/photos/ebothy/15723500675 - Incoming Data: https://www.flickr.com/photos/natspressoffice/13085089605 - Computer code: https://www.flickr.com/photos/n3wjack/3856456237/ - Road sign: https://www.flickr.com/photos/ell-r-brown/6804246004 - Car crash: EuroNCAP - Writing: https://www.flickr.com/photos/froderik/9355085596/ - Error screen: https://www.flickr.com/photos/lrosa/2867091465/ - Books: https://www.flickr.com/photos/mdales/48981707361/ - Pattery wheel: https://www.flickr.com/photos/61091655@N00/6831352744/ - Rocket launch: https://www.flickr.com/photos/gsfc/16495356966 - Stars: https://www.flickr.com/photos/gsfc/19125041621 Rob Allen ~ @akrabat