BUILDING A SUCCESSFUL API OVERNIGHT

@orliesaurus

BUILDING A SUCCESSFUL API OVERNIGHT

@orliesaurus

@orliesaurus

orlando@mashape.com

We are API fanatics. We are API hustlers. We build API tools.

UNIRESTAPIANALYTICS

getKONG

Interested in building API management tools:Proxies, Reverse proxies, Caching, Analytics,

UserManagement but also a friendly Market Place

100.000 API developers, thousands of APIs

HACKATHONS ARE COOL

IMPORTANT API NOTICE

• Everyone should use APIs: API economy, & API centric design

• APIs don’t have to be public

• If you don’t use APIs in 2015 you’re doing something wrong

LET’S DO THIS

• Introduction

• Architectures

• Endpoints

• Building

• Monetizing

• Marketing

• A look at the future…

FROM 0 TO 100To build something powerful you have to spend time

designing it properly

DEVELOPERS ARE LAZYArchitectural decisions

EVERYONE WANTS TO WIN• A painless experience for consumers

• Return data in simple flexible format (JSON vs XML)

• Insightful Errors

• Does what it says…right?

DEVELOPER EXPERIENCEDX - GO BIG OR GO HOME

API ARCHITECTURE

• REST (good)

• SOAP (uh-oh)

• RPC (lol)

• hyperREST (HATEOAS) - the unwanted child

• IDGAF (yolo)

RESTREST is not a standard but makes consumption of APIs faster, its CRUD.REST uses plain HTTP with JSON, mostly

REST can be cached

Natural to developers, SDKs, Docs

BLUEPRINTS

• Think as a Dev, Think use-cases

• RAML, APIBLUEPRINT, SWAGGER

• Worth the time WADL -> XMLSwagger -> JSONIODocs -> JSONRestDoc -> JSONAPIBlueprint -> MarkdownRAML -> YAML

DESIGN EDITORS

DESIGN EDITORS

SOAP- Independent of transport protocol (HTTP, FTP, UDP)

- XML

- SOAP Messages are envelopes (data,actions,headers,errors)

- Not just SSL but WS-Security

- Self-discoverable (WSDL) Self-retrying (WS-ReliableMessaging)

Some scenarios are ok..

ENDPOINTS SCIENCEPaint a pretty picture

MEANINGFUL URL

https://domain.com/api/path/something

Namespace Base resource Resource ID

Entry-point

..CAN GET COMPLEX

https://myapi.com/users/12e584/email.json

Namespace Base resource

Resource ID

Specific Resource

https://myapi.com/get_email_for/bob@mail.com

QUERY FILTERS

GET http://api.twitter.com/1/statuses/home_timeline.json?since_id=9999&max_id=1259

What is the best practice?

GET http://api.blog.com/v1/articles/1234/comments

GET http://api.blog.com/v1/comments?article=1234

USE VERBS

POST, GET, PUT, DELETE are kings

GET /customers/7236/invoices

CANIHAS /customers/7236/invoices

VS

USE VERBS

USE MORE VERBS

HEAD, OPTIONS, PATCH are available

PUT

PATCH

VS

HEADERSAn unseen blade is deadly

HEADERSEx:

Accept:Content-Type:

Accept-Charset: Authorisation: Cache-Control:

ETag

HEADERSShould we put API versions in the header?

Accept: application/vnd.steveklabnik-v2+json

RESPONSESThe good stuff

ERRORCODESMake ‘em mean something

RESPONSES{

"type": "car", "name": “My Ferrari",

"cylinders": 512, "options": { "seats": 4,

"turbospeed": 360 },

"allowedpassengers": { "family": ["Alice", “Bob”],“friends”:[“Charlie,Diana”]

}}

RESPONSES<car xmlns:xs="http://www.w3.org/2001/XMLSchema">

<name type="xs:string">My Ferrari</name> <cylinders type="xs:int">48</cylinders>

<optionals> <seats type="xs:int">4</seats>

<turbospeed type="xs:int">360</turbospeed> </optionals>

<allowedpassengers> <devices type="xs:list">

<device type="xs:string">cdrom</device> <device type="xs:string">harddisk</device>

</allowedpassengers> </boot>

</vm>

RESPONSES

“I’m so sorry…”

- every company returning XML

RESPONSES

RESPONSESCareful of Polymorphism

{ “fullname": "Peter File","user": {"username": "PeFile","userid": 123}

{ "username": “PeFile", "fullname": "Peter File", }

AUTHENTICATIONAll your bases are belong to us

AUTHENTICATION“Track Usage, Secure data”

Oauth (different versions)Basic authentication

Token Header

Key-in-the-bodyQuerystring

BUILDINGSmall steps, like lasagne

MOCKFake it till you make it

MOCKFake it till you make it

var Interfake = require('interfake');var interfake = new Interfake();

interfake.get('/users').status(200).body({ users: [ { id: 1, name: 'BOB 1' } ] });

interfake.get('/users/1').status(200).body({ id: 1, name: 'BOB' });var postResponse = interfake.post('/

users').status(201).body({ created : true });postResponse.creates.get('/users/2').status(200).body({ id: 2, name:

'ALICE' });postResponse.extends.get('/users').status(200).body({ items: [ { id: 2,

name: 'ALICE' } ] });

interfake.listen(1337);

MOCKFake it till you make it

$ curl http://localhost:1337/users -X GET

200{

"users" : [ {

"id":1 "name":"BOB"

} ]}

MOCKFake it till you make it

$ curl http://localhost:1337/users -X POST

201{

"created":true}

FRAMEWORKSUse them.

Rails/Rails-ApiExpress (Node)

Hapi (Node)Node-Restify

Flask(Python) / Flask-Restful (thx Twilio)Falcon (Python)Pecan (Python)

Werkzeug(Python)Interfake (Node - @basicallydan )

slimframework (PHP)Laravel (PHP)

STRUCTUREhttp://jsonapi.org/

MICROSERVICES

RELIABILITYLoad balancing to the win

SCALINGThere’s only a single direction…

StatelessMinimal

IdempotentCan afford errors

VERSIONINGIterate, Iterate, Iterate

TEST & DEBUGNothing is perfect

APIANALYTICSwrk

SPLUNK

LOGSTASH

$ > wrk -t12 -c400 -d30s http://127.0.0.1:8080/index.html

$ > Running 30s test @ http://127.0.0.1:8080/index.html 12 threads and 400 connections Thread Stats Avg Stdev Max +/- Stdev Latency 635.91us 0.89ms 12.92ms 93.69% Req/Sec 56.20k 8.07k 62.00k 86.54% 22464657 requests in 30.00s, 17.76GB read Requests/sec: 748868.53 Transfer/sec: 606.33MB

MONETIZINGEverything comes with a price

UTOPIAFREE

UTOPIAFREE

Facebook Amazon

Salesforce Twitter Shopify

LET’S BE HONESTFREEMIUM

Ex: Mailgun Twilio

Google Maps

INTENSEPAID

PROVIDER PAYSMoney Pot for Developers

MARKETINGReaching out to devs, like a boss.

EVENT STRATEGYHow to promote your API

HACKATHONSThe best way to gather feedback on your API

FIND GOOD HACKATHONSAs a developer you don’t have time to waste attending

bad hackathons

PREPARESwag packs (t-shirts and stickers), discount, codes, prizes

BE A FRIENDDon’t be a salesman

CONFERENCESSet up a booth, find partners

TRACKING & ANALYTICS

Signups Endpoint usage

Referrals/Coupons tracking Documentation analytics

DOCS & DEMOSBuild proof of concepts, great documentation, demos and

make it easy to be reached

SDKSAutomate them

DEV DOCS

Ex: Let’s analyse https://developer.github.com/v3/repos/collaborators/

BUILD INTEGRATIONSYet another way to market APIs

–Paddy Foran

“Good API design is not a matter of following principles, it’s a matter of fulfilling your users’

expectations while trying to maintain technical and semantic purity”

RECAPTime to wrap it up

• Design intuitive APIs, aimed for instant consumption with scalable stacks

• Use logs and do tests. Analyse what endpoints are used most and learn from it.

• Think of how developers will use your API. Find use-cases and illustrate them in the docs.

• By finding most common uses cases you can then make endpoints that make sense.

• Create a great developer experience by talking with your user-base.

@orliesaurus

orlando@mashape.com

TOOLS TO HAVE

• wrk - Stress test from the comfort of your localhost

• https://loader.io/ - LOAD TESTING

• https://www.blitz.io/ - GEO LOAD TESTING

• https://github.com/jakubroztocil/httpie - f**ks cURL CLI

• https://www.getpostman.com/ - f**ks the CLI

• http://luckymarmot.com/paw - f**ks the browser (macos)

FURTHER READING

• http://restcookbook.com/HTTP%20Methods/idempotency/

• http://mark-kirby.co.uk/2013/creating-a-true-rest-api/

• http://buff.ly/1vY4OsT

• http://swaxblog.tumblr.com/post/112611863175/who-cares-about-get-vs-post-norest

• https://www.youtube.com/watch?v=Pn9ucXr04r8

• https://speakerdeck.com/treeder/how-to-build-a-scalable-api