67
A Great API is Hard to Find Dan Diephouse MuleSoft @dandiep

A great api is hard to find

Embed Size (px)

Citation preview

Page 1: A great api is hard to find

A Great API is Hard to Find

Dan DiephouseMuleSoft

@dandiep

Page 2: A great api is hard to find

About Me

Page 3: A great api is hard to find

About MuleSoft

• Connect anything to everything!

• Publish APIs• Mediate services• Integrate applications• Load data• Over 100K dev community• 3200+ production

deployments

Page 4: A great api is hard to find

The Impact of APIs

Page 5: A great api is hard to find

API Proliferation

Source: Programmable Web

2005 2006 2007 2008 2009 2010 2011 2012

105 352 6011116

1628

2647

4676

9000

Page 6: A great api is hard to find

All contents Copyright © 2011, MuleSoft Inc.

6

API Billionaires Club 2011

Source: Programmable Web

Page 7: A great api is hard to find

The traditional 3-tier architecture

7

Presentation Tier

Middle Tier

Data Tier

Client

App Server

HTML

Database

Page 8: A great api is hard to find

…is being decomposed

8

Middle Tier

Data Tierdatabase

Client

Server

Data

JSON / XML JSON / XML

Presentation TierPresentation Tier

Page 9: A great api is hard to find

…is being decomposed

9

Middle Tier

Data Tierdatabase

Client

Server

Data

JSON / XML JSON / XML JSON / XML

Presentation TierPresentation Tier 3rd party Apps

Page 10: A great api is hard to find

…is being decomposed

10

Middle Tier

Client

Server

Data

JSON / XML JSON / XML JSON / XML

Presentation TierPresentation Tier 3rd party Apps

Data TierdatabaseSaaS, Infrastructure Services,

Social Media APIs

API API APIAPI

API

API

API

APIAPIAPI

API

API

Page 11: A great api is hard to find

Platform Shift

Traditional Application Environments

Application

Database

Web/App Server

Operating System

Page 12: A great api is hard to find

Platform Shift

New Application Environments

Application

Database

Web/App Server

Operating SystemIaaS

Application

PaaS

Page 13: A great api is hard to find

Technology Shift

Traditional Application Environments

Application

Database

Web Server

Operating System

Application

Business Logic

UI

Data

Security

Page 14: A great api is hard to find

Technology Shift

Newer Application Environments

Application

Database

Web Server

Operating System

Application

Business Logic

UI API

Data

Security

Integration

Page 15: A great api is hard to find

Technology Shift

Application Decomposition

Application

Business Logic

UI API

Data

Security

Integration

Page 16: A great api is hard to find

What APIs are you using?

• CRM – Salesforce, MS Dynamics, SAP• Data services – Xeround, Mongo, RDS• eCommerce – PayPal, QuickBooks, Xero, Freshbooks• Email – Amazon SES, SendGrid• Messaging – PubNub, Cloud AMQP• Notifications – Urban Airship, Twilio• Security – Katasoft• Social – Facebook, Twitter, LinkedIn• Storage – S3, DropBox

Page 17: A great api is hard to find

Changing business models

Build an eco-system of integrations which provide more value to your customers

Plethora of business models – fremium, pay for use, tiers, etc

Your API

CRM

ERPs

Marketing

HRM

eCommerce

Mobile

Page 18: A great api is hard to find

GREAT APIS

Page 19: A great api is hard to find

A GREAT API IS … USER FRIENDLY

Page 20: A great api is hard to find

What does the user want?

How do they want it?

Page 21: A great api is hard to find

Sidebar: REST is awesome!

Page 22: A great api is hard to find

5 interaction patterns to consider

choose the right one for the job

Page 23: A great api is hard to find

#1: CRUD + Actions

CreateRead

UpdateDelete

…Execute

POST /widgetsGET /widgetsGET /widgets?name=FooGET /widgets/123PUT /widgets/123DELETE /widgets/123

POST /widgets/123/execute

Page 24: A great api is hard to find

#2: Batch

“Web architects must understand that resources are just consistent mappings from an identifier to some set of

views on server-side state. If one view doesn’t suit your needs, then feel free to create a different resource that provides a better view (for any definition of “better”).

These views need not have anything to do with how the information is stored on the server, or even what kind of

state it ultimately reflects. It just needs to be understandable (and actionable) by the recipient.”

- Fielding

Page 25: A great api is hard to find

#2: Batch

Bulk Load

Get Job Status

POST /jobs[ { widget1 }, {widget2}, … ]

200 OKLocation /jobs/123

GET /jobs/123

[ status1, status2, status3, etc ]

Page 26: A great api is hard to find

#3: Streaming

Client APILong poll

Async events

Page 27: A great api is hard to find

#4:

• Instant notification for the web!• Example:– Client creates an invoice– Freshbooks calls HTTP webhook to synchronize

invoice to Salesforce

Page 28: A great api is hard to find
Page 29: A great api is hard to find

#5: Async

1.Send message POST /messages { … }

201 Received Location /messages/123

2. Check Status

GET /messages/123

Page 30: A great api is hard to find

A GREAT API IS … CORRECT*

* Except when it shouldn’t be

Page 31: A great api is hard to find

Details matter

Dates & Timezones

Error 500

GET

Hypertext

Content-Types

Stateful

Data modeling Pagination

Partial responses

Page 32: A great api is hard to find

Data TypesOrganizationServiceStub.AttributeCollection updateCollection = new OrganizationServiceStub.AttributeCollection();

OrganizationServiceStub.KeyValuePairOfstringanyType telephone = new OrganizationServiceStub.KeyValuePairOfstringanyType();telephone.setKey("telephone1");telephone.setValue("425-555-1212");

updateCollection.addKeyValuePairOfstringanyType(telephone);

Page 33: A great api is hard to find

Dates

{ createdAt : 124059811 …}

Page 34: A great api is hard to find

Dates

{ createdAt : “2008-03-01T13:00:00Z” …}

Page 35: A great api is hard to find

GET

GET /api/contacts/delete

200 OK

Page 36: A great api is hard to find

GET

DELETE /api/contacts/123

200 OK

Page 37: A great api is hard to find

Hypertext

GET /api/contacts

200 OK[ { “id” : “123” }]

Page 38: A great api is hard to find

Hypertext

GET /api/contacts

200 OK[ { “href” : “/api/contacts/123” “pictureHref” : “/api/contacts/123/johndoe.jpg” }]

Page 39: A great api is hard to find

A GREAT API IS … SECURE

• A GREAT API IS…SECURE

Page 40: A great api is hard to find

Do you think you’re special?

Page 41: A great api is hard to find

“Special” Companies• Microsoft

(WS-Security/Policy + Live ID variant)

• QuickBooks (SAML/OAuth variation)

• AWS (Custom encryption)

Normal Companies• Salesforce (OAuth 2 or Basic

Auth*)• Twitter (OAuth 1)• Facebook (OAuth 2)

Page 42: A great api is hard to find

Basic Auth + SSL

• Easy• Accessible• Not great for public APIs…

Page 43: A great api is hard to find

OAuth!

• 1.0: out of band tokens• 2.0:– 2 legged authentication– No more encryption of tokens– Short lived tokens with expiration & refresh– Grant types

Page 44: A great api is hard to find

WS-Security

Page 45: A great api is hard to find

A GREAT API IS … DOCUMENTED

Page 46: A great api is hard to find

• TODO: screenshots– Amazon

Page 47: A great api is hard to find

• Magento

Page 48: A great api is hard to find

• Apiary

Page 49: A great api is hard to find
Page 50: A great api is hard to find

A GREAT API IS … VERSIONED

Page 51: A great api is hard to find

POST /api/v1/foo

Page 52: A great api is hard to find

POST /api/1.0/foo

Page 53: A great api is hard to find

POST /api/2012-01-01/foo

Page 54: A great api is hard to find

POST /api/foo?v=2012-01-01

Page 55: A great api is hard to find

POST /api/fooVersion: 1.0

Page 56: A great api is hard to find

POST /api/fooContent-Type: application/vnd.foo+json;v=1.0

Page 57: A great api is hard to find

Things to consider

• Include versioning from the start• How long should you maintain versions?• How often will you make changes?• Will you have minor versions?• Date based?

Page 58: A great api is hard to find

Which approach

Header• Potentially more “correct”

HATEOS approach

URL• Easier to hack in the

browser & with curl• Provides clarity when there

are structural changes– e.g. it’s clear that resource

/foo went away in version 2

Page 59: A great api is hard to find

A GREAT API … FAILS GRACEFULLY

Page 60: A great api is hard to find

A great error has

1. A machine understandable HTTP status code2. An end user message3. If relevant, details for the developer to

escalate the issue (tracking #)

Page 61: A great api is hard to find

POST /foo{ … bad data … }

200 OK{ “message” : “Invalid request”}

Page 62: A great api is hard to find

POST /foo{ … bad data … }

400 Bad RequestContent-Length: 0

Page 63: A great api is hard to find

Good

POST /foo{ … bad data … }

400 Bad Request{ “message” : “The field foo123 is not allowed on the request.”}

Page 64: A great api is hard to find

Good

POST /contacts{ “name” : “Dan Diephouse” }

409 Contact Exists{ “message” : “A contact with that name already exists.”}

Page 65: A great api is hard to find

Good

POST /contacts{ “name” : “Dan Diephouse” }

500 Error{ “message” : “We were not able to process you’re request due to an unexpected error. Please contact support for help in resolving this request (Request ID 19022334).” “requestId” : 19022334 “time” : “2012-03-01T13:00:00Z”}

Page 66: A great api is hard to find

A Great API

• User friendly• “Correct”• Secure• Documented• Versioned• Fails Gracefully

Page 67: A great api is hard to find

Questions?

@[email protected]