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