YOUR API SPEC ISN’T WORTH THE PAPER IT’S WRITTEN ON

@APIWORLD 2019 SAN JOSE

GARETH JONES

PRINCIPAL API ARCHITECT

@GARETHJ_MSFT

This Photo by Unknown Author is licensed under CC BY-SA

YOU ARE AN API OWNER. YOU ARE FEELING SMUG.

Open API 3.0 description

Generated SDKs

Automated tests

Pervasive monitoring

This Photo by Unknown Author is licensed under CC BY-SA-NC

YOU DEPLOY A NEW BUILD

This Photo by Unknown Author is licensed under CC BY-NC-ND

This Photo by Unknown Author is licensed under CC BY-NC This Photo by Unknown Author is licensed under CC BY-SA-NC

CONSUMER/PRODUCER CONTRACT

This Photo by Unknown Author is licensed under CC BY-SA

UNDERSPECIFIED CONTRACT

This Photo by Unknown Author is licensed under CC BY

BREAKING CHANGES

This Photo by Unknown Author is licensed under CC BY-NC-ND

DESIGN YOUR BREAKING CHANGE BAR

@garethj_msft

HYRUM’S LAW

With a sufficient number of users of an API,

it does not matter what you promise in the

contract:

all observable behaviors of your system

will be depended on by somebody.

NUMBER OF THINGS GROWS

• Array size grows from 0 to 1

• Array size grows from 1 to n

• Array size grows from < 1 page to >

1 page

This Photo by Unknown Author is licensed under CC BY-SA

SIZES OF THINGS GROW

Image sizes get big

Overall packet sizes get too big

Example: major retailer 10mb packet

Android device can’t handle it with some json stacks

PERFORMANCE, UP DOWN

Lower or higher latency

New race conditions

Higher latency

Unresponsive UI

Batch exceeds acceptable timeframe

This Photo by Unknown Author is licensed under CC BY

DREADED AUTH CHANGES

This Photo by Unknown Author is licensed under CC BY-SA

WEBHOOK DENSITY CHANGES

This Photo by Unknown Author is licensed under CC BY-SA

HYPERMEDIA DOMAIN CHANGES

This Photo by Unknown Author is licensed under CC BY-SA-NC

QUERY PARAMETER COMBO MOVES

This Photo by Unknown Author is licensed under CC BY-SA

HOW CAN WE PROTECT OURSELVES?

PROVIDE A CHAOS MOCK ENDPOINT STRETCH EVERY BOUNDARY CASE

This Photo by Unknown Author is licensed under CC BY

RANDOMLY DISOBEY CONSUMER PREFERENCES

This Photo by Unknown Author is licensed under CC BY

WATCH THOSE LOGS AFTER A DEPLOYMENT

This Photo by Unknown Author is licensed under CC BY

CONSIDER THESE CASES AS BREAKING CHANGES

This Photo by Unknown Author is licensed under CC BY-NC-ND

Oh, one last thing…

21

THANK YOU @garethj_msft