Zend Expressive - An Introduction For API Building

A presentation by @stuherbert  for @GanbaroDigital Zend Expressive An Introduction
For API Building

Industry veteran: architect, engineer, leader, manager, mentor F/OSS contributor since
1994 Talking and writing about PHP since 2004 Chief Software Archaeologist Building Quality @GanbaroDigital About Stuart

Follow me I do tweet a lot about non-tech stuff
though :) @stuherbert

@GanbaroDigital ?? ?? What framework(s) do you currently use for
building APIs?

@GanbaroDigital Zend Expressive is my framework of choice for building
JSON API services.

@GanbaroDigital I'm here to show you how I currently use
Zend Expressive for building API services.

@GanbaroDigital This is just how I go about it. I'm
here to learn from you too.

@GanbaroDigital In This Talk 1. Why Zend Expressive 2. Getting
Started 3. Organising Your Code 4. Essential Elements 5. Testing Your API

@GanbaroDigital I won't be comparing Zend Expressive against other frameworks.

@GanbaroDigital Why Zend Expressive?

@GanbaroDigital ?? ?? How can a framework help you build
your API?

@GanbaroDigital https://ﬂic.kr/p/uTwoPu

@GanbaroDigital 1. Framework Isolation

@GanbaroDigital To explain what this is, let's look at what
happens when your API gets called.

@GanbaroDigital Bootstrap Routing Dispatch Response Controller Features

@GanbaroDigital Bootstrap Routing Dispatch Response Framework Controller Features

@GanbaroDigital Bootstrap Routing Dispatch Response Framework Glue Code Controller Features

@GanbaroDigital Bootstrap Routing Dispatch Response Framework Glue Code Business Logic
Controller Features

@GanbaroDigital I want to be able to upgrade / replace
the framework without touching anything else.

Controller Features

@GanbaroDigital Bootstrap Routing Dispatch Response Framework v.Next Glue Code Business
Logic Controller Features

@GanbaroDigital “Framework upgrades are very expensive. By isolating the framework,
I can keep that cost under control.

@GanbaroDigital This means that the "glue code" can't depend on
the framework.

@GanbaroDigital Neither can anything in the business model or data
model.

@GanbaroDigital This has other beneﬁts.

@GanbaroDigital 2. Glue Re-use

@GanbaroDigital “ The more time I can spend on features,
the more productive I am.

Controller Features

@GanbaroDigital PSR-7 / PSR-15 give me middleware and framework isolation.

Controller Features

Controller Features Middleware Middleware Middleware Features

@GanbaroDigital Each piece of middleware is a standalone piece of
logic.

@GanbaroDigital It knows nothing about any other middleware. It knows
nothing about the controller / action at the end of the pipeline.

@GanbaroDigital 3. Change Isolation

@GanbaroDigital “ The #1 cause of new defects in working
code is change.

@GanbaroDigital By isolating code, I can isolate the impact of
code changes.

@GanbaroDigital I would rather repeat isolated code than have brittle
DRY code.

@GanbaroDigital “ Today's repeated code isn't always tomorrow's repeated code.

@GanbaroDigital 4. Ability To Reason

@GanbaroDigital PHP's core strength is just how damned deterministic its
execution model is.

@GanbaroDigital Anything that obfuscates it, or introduces non-determinism, increases your
defect count.

@GanbaroDigital Everything is traceable.

@GanbaroDigital Everything is testable on its own.

@GanbaroDigital Motivations Recap 1. Framework Isolation 2. Glue Re-use 3.
Change Isolation 4. Ability To Reason

@GanbaroDigital Zend Expressive satisﬁes all my motivations.

@GanbaroDigital Your motivations may be different. Nothing wrong with that!

@GanbaroDigital Getting Started

@GanbaroDigital https://unsplash.com/photos/RFId0_7kep4 Guided Installation

@GanbaroDigital composer create-project  zendframework/zend-expressive-skeleton   <your-app-name>

@GanbaroDigital Here's what I use when building JSON APIs.

@GanbaroDigital

@GanbaroDigital The modular structure helps me achieve code isolation.

@GanbaroDigital

@GanbaroDigital I haven't felt the need to try any of
the others.

@GanbaroDigital Coding against PSR-11 means there's no obvious beneﬁt switching
between modern DI containers.

@GanbaroDigital

@GanbaroDigital My Zend Expressive API apps spend around 20% in
the 'framework' column. Reducing that overhead is important to me.

@GanbaroDigital

@GanbaroDigital I don't use any templating at all (yet) in
my API apps.

@GanbaroDigital I'm interested in creating self-documenting APIs one day. I
will use Twig when that happens.

@GanbaroDigital

@GanbaroDigital We'll come back to error handling shortly.

@GanbaroDigital Organising Your Code

@GanbaroDigital Zend Expressive uses a different layout than (say) Wordpress.

@GanbaroDigital Folder Structure Created By Installer

@GanbaroDigital config/ Config files - yours & the framework's Folder
Structure Created By Installer

@GanbaroDigital config/ data/ Config files - yours & the framework's
Config cache home Folder Structure Created By Installer

@GanbaroDigital config/ data/ public/ Config files - yours & the
framework's Config cache home Static assets (largely unused in APIs) Folder Structure Created By Installer

@GanbaroDigital In something like Wordpress, everything lives in the 'public'
folder AKA the DocRoot

@GanbaroDigital config/ data/ public/ src/ Config files - yours &
the framework's Config cache home Static assets (largely unused in APIs) Your glue code and business logic Folder Structure Created By Installer

@GanbaroDigital config/ data/ public/ src/ test/ Config files - yours
& the framework's Config cache home Static assets (largely unused in APIs) Your glue code and business logic Unit tests for what's in src/ Folder Structure Created By Installer

@GanbaroDigital config/ data/ public/ src/ test/ vendor/ Config files -
yours & the framework's Config cache home Static assets (largely unused in APIs) Your glue code and business logic Unit tests for what's in src/ Packages installed via composer Folder Structure Created By Installer

@GanbaroDigital Zend Expressive uses PSR-4 autoloading to load each module
in your app.

@GanbaroDigital config/ data/ public/ src/ test/ vendor/ Config files -
yours & the framework's Config cache home Static assets (largely unused in APIs) Your glue code and business logic Unit tests for what's in src/ Packages installed via composer Folder Structure Created By Installer

@GanbaroDigital src/ Folder Structure Created By Installer

@GanbaroDigital src/ App/ Folder Structure Created By Installer Your module

@GanbaroDigital src/ App/ src/ PSR-4 Namespace starts here Folder Structure
Created By Installer Your module

@GanbaroDigital { ..., "autoload": "psr-4": { "App\\": "src/App/src" } },
... }

@GanbaroDigital src/ App/ src/ <code> PSR-4 Namespace starts here Folder
Structure Created By Installer Your namespaced code Your module

@GanbaroDigital src/ App/ src/ <code> ConﬁgProvider.php PSR-4 Namespace starts here
Folder Structure Created By Installer Your namespaced code DI container / template conﬁg Your module

@GanbaroDigital src/ App/ src/ <code> ConﬁgProvider.php templates/ PSR-4 Namespace starts
here Folder Structure Created By Installer Your namespaced code DI container / template conﬁg Your module Your views

@GanbaroDigital First thing I do is replace 'App' with a
sensible namespace, e.g. GanbaroDigital\BillingAPI\Core

@GanbaroDigital src/ App/ Modular Folder Structure

@GanbaroDigital src/ Core/ Modular Folder Structure Dumping ground

@GanbaroDigital Then I add modules to provide functionality to business
logic.

@GanbaroDigital src/ Core/ Storage/ Health/ Datastore abstraction Modular Folder Structure
Health check API Dumping ground

@GanbaroDigital And modules for individual business logic areas.

@GanbaroDigital src/ Core/ Storage/ Health/ Invoices/ Payments/ Datastore abstraction Modular
Folder Structure Health check API Business logic Dumping ground More business logic

@GanbaroDigital I prefer to have each API path route to
its own module. e.g. /u/ganbarodigital/invoices /u/ganbarodigital/payments

@GanbaroDigital One of the really nice things about Zend Expressive
is that you can have whatever structure suits you.

@GanbaroDigital Essential Elements

@GanbaroDigital Zend Expressive provides a great platform for building API
services.

@GanbaroDigital Out of the box, it isn't a 100% ready-to-go
API framework.

@GanbaroDigital Most of what we need can be handled by
building some middleware.

@GanbaroDigital A couple of things need adding as services built
by the DI container.

@GanbaroDigital Logging

@GanbaroDigital https://speakerdeck.com/stuartherbert/designing-for- disaster-preparing-your-code-for-emergencies

@GanbaroDigital Logging Needs ... 1. A logger in the DI
container 2. Middleware to log all requests & responses 3. Middleware to add extra metadata

@GanbaroDigital Use: Psr\Log\LoggerInterface as the request key into the DI
container.

@GanbaroDigital Have the DI container return a Monolog instance. You
need Monolog's support for customising the logger after it has been created.

@GanbaroDigital i.e. an 'immutable' logger is about as much use
as a chocolate ﬁreguard here!

@GanbaroDigital Gradually add metadata ﬁelds to help you ﬁnd relevant
logs. Think of them like database indexes.

@GanbaroDigital Add a 'uid' metadata: unique ID for that API
request

@GanbaroDigital LogRequestsAndResponses: middleware to add initial metadata to the logger
& capture inputs and outputs

@GanbaroDigital Add a 'request-id' metadata: trace API calls across your
architecture.

@GanbaroDigital In the Authentication middleware, add a 'user-id' to the
logger's metadata.

@GanbaroDigital Error Handling

@GanbaroDigital Error Handling Needs ... 1. Common code for RFC
7807 responses 2. Common exception for error responses 3. Middleware to handle the common exception 4. Middleware for 404 Not Found handling

@GanbaroDigital RFC 7807 deﬁnes a common format for API responses
when an error has occurred.

@GanbaroDigital I have my business logic throw an 'ApiError' exception.
The business logic creates the appropriate Response and stuffs it inside the exception.

@GanbaroDigital https://speakerdeck.com/stuartherbert/  5-patterns-to-improve-application-robustness

@GanbaroDigital To catch (and log!) ApiError exceptions, I add a
'HandleApiErrors' middleware to my app's pipeline.

@GanbaroDigital I add a 'NotFoundHandler' to generate RFC 7807 responses
for HTTP 404 errors.

@GanbaroDigital Validation

@GanbaroDigital Validation Needs ... 1. application/vnd+ Content-Type 2. JSON schema
for input payloads 3. Middleware to validate against JSON schema 4. (optional) JSON schema for output payloads

@GanbaroDigital I don't use application/json as my API Content-Type.

@GanbaroDigital application/vnd+billingapi.invoice.v1

@GanbaroDigital https://speakerdeck.com/stuartherbert/  json-schema-for-validating-api-requests

@GanbaroDigital Add middleware to look at the incoming Content-Type and
validate the payload against the matching JSON schema.

@GanbaroDigital The same middleware can also validate all of your
API responses.

@GanbaroDigital Authentication

@GanbaroDigital Authentication Needs ... 1. An identity provider 2. Middleware
to handle CORS requests 3. Middleware to authenticate a user 4. Middleware to authorise a user

@GanbaroDigital An identity provider is a user database + UI
all in one.

@GanbaroDigital A commercial one like auth0.com might be easier than
building your own.

@GanbaroDigital The CORS spec mandates that some CORS-requests are always
unauthenticated.

@GanbaroDigital If your API can be called directly from JavaScript
running in browsers, you must handle authentication inside your API app.

@GanbaroDigital The world is moving to JavaScript consuming APIs. And
better data privacy laws. Add support upfront.

@GanbaroDigital Use separate middleware items for authentication and authorisation.

@GanbaroDigital Keep authorisation simple. Use OAuth2 scopes, not RBAC.

@GanbaroDigital In practice, RBAC schemes perform very poorly.

@GanbaroDigital Metrics

@GanbaroDigital Metrics Need ... 1. Metrics infrastructure (e.g. Prometheus) 2.
A statsd client

@GanbaroDigital https://speakerdeck.com/stuartherbert/designing-for- disaster-preparing-your-code-for-emergencies

@GanbaroDigital There's no PSR for a metrics client today.

@GanbaroDigital Add your preferred metrics client to the DI container.

@GanbaroDigital Call the client throughout your code to report timings
and counters.

@GanbaroDigital Don't use middleware to track your API response times.
Get these timings from your Nginx logs.

@GanbaroDigital Rate Limiting

@GanbaroDigital Most APIs need to protect themselves from their heaviest
users.

@GanbaroDigital A common approach is to limit the number of
requests per user, per time period.

@GanbaroDigital Rate Limiting Needs ... 1. Identity provider to provide
user IDs 2. Redis to track API usage 3. Middleware to update API usage 4. Cron job to reset API usage 5. Auto-scaling infrastructure

@GanbaroDigital Redis gives us atomic increment / decrement.

@GanbaroDigital Using an external store like Redis makes auto-scaling possible.

@GanbaroDigital Add middleware to decrement per-user rate allowance and return
errors when the allowance is used up.

@GanbaroDigital The middleware can also add headers to responses to
tell end-users what their remaining allowance is.

@GanbaroDigital Easiest way to give the end-user their next allowance
is from a cron job or equivalent.

@GanbaroDigital Don't build cron features into your API service. Use
the real thing.

@GanbaroDigital In practice, per-user rate limits don't protect you when
everyone wants to use the API at the same time.

@GanbaroDigital Auto-scaling infrastructure is your friend there.

@GanbaroDigital Testing APIs

@GanbaroDigital Write unit tests for individual components.

@GanbaroDigital Write end-to-end tests for the API as a whole.

@GanbaroDigital https://getpostman.com

Thank You Can We Help You? A presentation by @stuherbert 
for @GanbaroDigital

Zend Expressive - An Introduction For API Building

Zend Expressive - An Introduction For API Building

More Decks by Stuart Herbert

Other Decks in Programming

Featured

Transcript