API TOOLS AND

TECHNIQUESJason Harmon

@jharmn

AGENDA

Design Scale

• API specification formats

API Management

Debugging & Testing

• Request/Response capture

• Testing approaches

Analytics

SCALEA slightly different look

DESIGN SCALE

Problems

• Producing consistent

designs

• Prototyping and rapid

design iteration

• Generate code from

design

• Generate docs from

design

API SPECIFICATIONS

• A format to describe operations

• Produced by implementation, or design-first

• Allows for codegen of client or server, as well as

documentation

• Mock APIs with sample responses from spec

• Quick feedback from clients from design-first allows for

rapid iteration

HISTORY OF API SPECS

API SPECIFICATION

FORMATS• WADL

• WSDL 2.0

• Google Discovery

Document

• IODocs

• Swagger

• Blueprint

• RAML

WADL & WSDL 2.0

• 2007: http://www.w3.org/TR/wsdl20/

• 2009: http://www.w3.org/Submission/wadl/

• Neither was ever finalized

• Considered to be largely experimental

artifacts with little adoption

GOOGLE DISCOVERY

DOCUMENT• 2010?:

https://developers.google.com/discovery/v1/referen

ce/apis

• Created primarily for discovery (thus the name)

• Still in use at Google

• JSON Schema-based

• Very little adoption

IODOCS

• 2011: https://github.com/mashery/iodocs

• OSS project by API management vendor

Mashery

• JSON-Based

• Largely used by customers in the Mashery

ecosystem

SWAGGER

• 2011: http://swagger.io/

• OSS by Reverb (https://helloreverb.com/), maker of the Reverb app

• Meant to produce spec from implementation

• Recent additions allow for design-first

• Hyperactive OSS community engagement

• Integrated with many products

• Now in version 2.0

BLUEPRINT

• 2013: https://apiblueprint.org/

• Created by Apiary (http://Apiary.io) (an API

portal platform) as standard for their platform

• Markdown-based

• First spec format to switch from code-first to

design-first

RAML

• 2013: http://raml.org/

• Created by Mulesoft, a long-standing SOA/ESB/API vendor, as

standard for their platform

• YAML-based

• Design-first

• Resource type definition/traits

• Now in version 2.0

CURRENT STATE• Swagger & RAML are in version 2.0

• Swagger is the only player not profiting directly from the spec,

powered through partnerships

• Swagger has an incredible following in the OSS community

• Swagger added design-first later, RAML was design-first up-

front

• RAML seems to be well received by the enterprise community

• Blueprint continues to gain adopters; recent additions of

hypermedia

TRENDSDesign-first + Mocking

• Start slow to go fast

• Get API client feedback on

mock APIs

• Real usability is only

measurable with tactile

feedback

• Weakness: multi-scenario

and errors are hard to mock

TRENDS

Interactive editors

• Non-JSON formats growing in popularity for readability

• Swagger 1.5 added YAML-based

• RAML is YAML

• Blueprint is Markdown

Swagger Editor

DEVELOPER DEBUGGING

• Figure out why calls aren’t working

• Save calls to make retry simpler

POSTMAN

• Loved by developers

• Easy to use locally

• Simple Chrome plugin

• Some limitations in being

from browser

• Not great for sharing within a

team

POSTMANAble to create & save requests in collections

Parameterize requests

Import/export collections

COMMAND-LINE

Requires no UI

Works on any machine

Save calls as text

cURL is the lingua franca

of APIs

HTTPie is gaining

popularity

http://curl.haxx.se/

HTTPiehttps://github.com/jakubroztocil/httpie

CURL - LINGUA

FRANCA

CURL - LINGUA

FRANCA

CURL - PHP NATIVEAlso batteries included in many other languages

DEBUGGING

Request/response capture

• Amazing for developers + support

• Figure out why calls aren’t working

• Often a great setup for testing, from captures

• Implemented by using an HTTP proxy

CAPTURE

Consum

erProxy Server

Request

Respons

e

Capture

api.something.comhttps://api-something-com-74776xpbe6nt.runscope.net/

CAPTURE IS IN ONE

PLACERunscope bought up just about everything

They’re experts at capture

REQUESTB.INYet another “Runscope Community Project”

HURL.ITYet another “Runscope Community Project”

RUNSCOPESimple to change your hostname to Runscope's

Locally hosted proxy available

Great for debugging webhooks

TESTINGAPI tests are about

consumers making calls

LOTS OF

DEVELOPMENTAPI testing is still rather cutting edge

Many new options, not many clear picks

UNIT TESTING IS NOT

ACCEPTANCE TESTING

Only an API consumer is an effective API test

AC IS PROBABLY NOT FROM

PRODUCT MANAGERSThey don’t usually understand APIs

http://apiux.com/2014/02/13/api-product-manager/

BALLMER GETS ITAPIs are the developers’ world

TESTING TOOLSThere’s no reason to have a buggy API

Work like a craftsman

CUCUMBERBehavior Driven Development

http://www.pragmaticapi.com/blog/2013/11/10/bdd-for-apis-talk-at-

apistrat-sf-2013

BDD ALTERNATIVESFrisby.js

CURL FOR API

TESTINGDeath by a thousand paper cuts

RUNSCOPETests derived from proxy/captures

SOAPUI (BY

SMARTBEAR)It’s called…SOAP

You can host it completely locally

READY API (BY

SMARTBEAR)Private cloud, capture, API virtualization/mocking,

load testing, more

ANALYTICSMeasure what you treasure

ANALYTICS

Before you do anything:

KPIs for APIs by John Musser

• Formerly of ProgrammableWeb

• Now runs API Science

https://www.youtube.com/watch

?v=UFjgbsRrLHw

http://www.slideshare.net/jmuss

er/kpis-for-apis

CALLS…?There’s more to it.

MEASUREMENT

OVERLOAD

• Performance, defect rate, stability, support

tickets

• Customer satisfaction/NPS, adoption, churn

• Channel performance, revenue, market

share

SLOW

DOWN.

BREATHE.There are a massive

amount of things to

measure

DEFINE

YOUR

FUNNELSWhere do you gain value?

PLAYERSApp Users

Apps

Developers

Your APIs

Your Company

VOLUME IS NOT VALUEHigh call volume doesn’t mean you’re doing it

right

MEASURE

INSIDE AND

OUTInternal API metrics are

critical

You may learn things about

your value chain

(see Netflix and LinkedIn)

TTFHW“Time to first hello world”

Helps measure Developer Experience (DX)

MICROSERVICESOptimize your scale

Scale up where volume calls for it

DASHBOARDING

• Think about events

• Analyze funnels

• MongoDB/Couch/etc is

tempting

• Keen.io makes it easier

PERFORMANCE METRICS

• API Management Vendors

• All provide this core functionality

• DIY: Often fits into existing metrics

• Mongo/Couch solutions abound

• Often standard web metrics platforms will do the

trick

API MANAGEMENT

VENDORS

GALORE3Scale

Apigee

Axway/Vordel

CA Technologies

IBM

Mashery/Intel

Mulesoft

SOA Software

WS02

MORE

STUFF THAN

YOU THINK

Routing/Provisioning

Packaging

Rate limiting

Event processing

Monitoring

Analytics

Security/Auth

Caching

Geodistribution

MORE THAN JUST A

PROXY

Consum

erProxy Server

LOTS

TIME TO

MARKETDIY:

• Big investment

• Long timeline

• Ongoing maintenance

• NGINX leading solutions

for proxy aspect

THANKS!