Designing Your API First.
Tips, Tools and Stories for designing and building better APIs
@matthewtrask
Who am I?
API Nerd
2x Podcast Host
Cyclist
Photography
@matthewtrask
Quick warning
there's a lot of gifs. get ready.
@matthewtrask
The physical activity portion:
@matthewtrask
who here codes first, ask questions later?
In most projects, the biggest challenge to solve isn't the technology, its communication
@matthewtrask
@matthewtrask
Who you communicate with?
Integration/Service teams
Executives
QA people
Ops people
Consumers (non-team)
@matthewtrask
OpenAPI and Design First Processes help make communication easy.
@matthewtrask
Lets Define a Few Things
@matthewtrask
OpenAPI Initiative (OAI)
Backed by the Linux Foundation, this is a volunteer lead and run org that maintains the OpenAPI specification, drives changes and improvements as well as helps plan events around OpenAPI
API Specifications Conference if you want to deep dive this stuff
@matthewtrask
OpenAPI Specification (OAS)
A human and machine readable specification to describe APIs. It covers the paths, requests, and responses of your API.
One very important thing to note...
@matthewtrask
OpenAPI
@matthewtrask
OpenAPI Ecosystem
@matthewtrask
API Contract
The API Contract is a document built by the API provider which provides a list of available routes as well as required information such as query params, request body params, response body, security schemes, and more.
This contract is provided as a way to explicitly build trust amongst consumers.
Like the prod database and main git branch, this is your source of truth for API interactivity in your application.
@matthewtrask
API Documentation
Using tools that understand the OpenAPI, you can build interactive documentation, and automate documentation changes.
The old way
hey do you have any docs on this service?
@matthewtrask
The old way
nah, just read the code
@matthewtrask
The old way
<?php
public function getTreePlanted(string $orderId, string $treeId)
{
$url = sprintf('%s/%s', $this->buildBaseUrl('Trees%20Planted'), $treeId);
$response = Http::withHeaders([
'Authorization' => sprintf('Bearer %s', config('airtable.key'))
])->get($url);
$data = $response->object()->fields;
$tree = Tree::updateOrCreate([
'tree_id' => $treeId,
], [
'order_id' => $orderId,
'species' => $data->Species[0],
'planted_on' => $data->CreatedDate,
'site_id' => $data->Sites[0]
]);
if (!$tree->location()->exists()) {
$tree->location()->create([
'latitude' => ltrim(rtrim(Str::before($data->Coordinates, ','))),
'longitude' => ltrim(rtrim(Str::after($data->Coordinates, ','))),
'three_words' => $data->What3Words ?? ''
]);
} else {
Log::info(sprintf('tree has location: %s', $treeId));
}
if (!$tree->photos()->exists()) {
if (isset($data->Image[0]->thumbnails)) {
foreach($data->Image[0]->thumbnails as $key => $image) {
$tree->photos()->create([
'image_id' => $data->Image[0]->id,
'type' => $key,
'width' => $image->width,
'height' => $image->height,
'url' => $image->url
]);
}
} else {
Log::info(sprintf('tree has photos: %s', $treeId));
}
}
}
The code
@matthewtrask
The old way
ad-hoc docs
@matthewtrask
@matthewtrask
@matthewtrask
It's 2021, we can do better.
With OpenAPI and a Design First Process
@matthewtrask
It's 2021, we can do better.
Design First API Processes flip the way we are generally used to building an API.
Instead of coding first, and then documenting. We document first, iterate with stake holders and teams, and then write the code.
Pros of Design First API Processes
@matthewtrask
Pros of Design First API Processes
@matthewtrask
Shortened Feedback Loop
Pros of Design First API Processes
@matthewtrask
Collaborative
Pros of Design First API Processes
@matthewtrask
Iterative
Text
Pros of Design First API Processes
@matthewtrask
Time/Money Saving
Text
Cons of Design First API Processes
@matthewtrask
Perfect being the enemy of good.
Cons of Design First API Processes
@matthewtrask
Non technical managers not seeing progress
@matthewtrask
Big Question
Is the code first approach that bad?
Short answer: not really.
Long answer: it depends on what you are doing.
API Design Principles
@matthewtrask
1. Your API is the first user interaction of your application
API Design Principles
@matthewtrask
2. Your API comes first, implementation second.
API Design Principles
@matthewtrask
3. Your API is described (and maybe even self-descriptive).
The Process
@matthewtrask
Align - Define - Design - Refine
James Higginbotham - @launchany
The Process
@matthewtrask
Align
Get all stakeholders on the same path.
The Process
@matthewtrask
Align
The Process
@matthewtrask
Define
Map stakeholder requirements onto a defined document
The Process
@matthewtrask
Define
The Process
@matthewtrask
Design
Take the definition and flesh out OpenAPI Document
The Process
@matthewtrask
Design
The Process
@matthewtrask
Refine
Refine the definition document through testing and
The Process
@matthewtrask
Refine
Tools
@matthewtrask
OpenAPI
Stoplight Studio
Tools
@matthewtrask
OpenAPI
A descriptive human and machine readable specification. Can be used for documentation, SDK generation, testing, mocking and more.
Tools
@matthewtrask
OpenAPI
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: http://petstore.swagger.io/v1
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
responses:
'200':
description: A paged array of pets
headers:
x-next:
description: A link to the next page of responses
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
Tools
@matthewtrask
Stoplight Studio
https://stoplight.io/studio
Visual Editor
Mocking
Linting
Documentation
Lets Design an API
@matthewtrask
Lets Design an API
@matthewtrask
What kind of API should we design?
Lets Design an API
@matthewtrask
Align
What do we want this API to be able to do?
Lets Design an API
@matthewtrask
Define
Define the desired endpoints and models
Lets Design an API
@matthewtrask
Design
To Stoplight we go!
Lets Design an API
@matthewtrask
Refine
What can we do better?
What can we consolidate?
What can we remove?
Lets Design an API
@matthewtrask
Are we happy?
How can we integrate OAS into a PHP app?
@matthewtrask
PHP Tools for OAS
@matthewtrask
https://github.com/primitivesocial/openapi-intializer
CLI Tool to scaffold an OpenAPI (Laravel only)
PHP Tools for OAS
@matthewtrask
https://api-platform.com
All in one platform for Symfony with OAS support
PHP Tools for OAS
@matthewtrask
https://github.com/thephpleague/openapi-psr7-validator
Framework agnostic request/response validator
PHP Tools for OAS
@matthewtrask
https://github.com/cebe/php-openapi
Framework agnostic way to dynamically write your OAS document. Great way to build docs on existing application.
What comes next?
@matthewtrask
1. Share API Document amongst team.
Either export documentation so everyone can view it locally, or share the yml/json to import into Stoplight Studio
What comes next?
@matthewtrask
2. Begin Implementation
Using Mocking via Stoplight Studio lets the Front End/iOS/Android Developers develop in tandem with back end developers working on the API implementation.
What comes next?
@matthewtrask
3. Integrate OAS tooling into CI/CD pipelines
Stoplight Spectral for linting
Optic to interactively watch for API changes
Dredd for implementation testing
PHPUnit because we are good PHP developers of course
What comes next?
@matthewtrask
4. Work out strategy for deploying Documentation Changes
Optic provides a way to watch both the API Contract and the code to find discrepencies
Resources
@matthewtrask
OpenAPI Specification
https://github.com/OAI/OpenAPI-Specification
Documentation and examples
Resources
@matthewtrask
Stoplight.io
Studio: interactive API contract builder
Spectral: CLI listing with customizable rules
Prism: mocking server built into Studio
Resources
@matthewtrask
useoptic.com
Interactive watcher that will compare API Document to implemented code to spot discrepancies before you deploy 🚀
Resources
@matthewtrask
openapi.tools
curated list of OpenAPI supported tooling from documentation to testing, mocking to linting.
@matthewtrask
Questions?
@matthewtrask
Thanks!
@matthewtrask
mjftrask@gmail.com
Designing your API First.
By Matt Trask
Designing your API First.
- 232