Transcript
A Great API is Hard to Find
Dan DiephouseMuleSoft
@dandiep
About Me
About MuleSoft
• Connect anything to everything!
• Publish APIs• Mediate services• Integrate applications• Load data• Over 100K dev community• 3200+ production
deployments
The Impact of APIs
API Proliferation
Source: Programmable Web
2005 2006 2007 2008 2009 2010 2011 2012
105 352 6011116
1628
2647
4676
9000
All contents Copyright © 2011, MuleSoft Inc.
6
API Billionaires Club 2011
Source: Programmable Web
The traditional 3-tier architecture
7
Presentation Tier
Middle Tier
Data Tier
Client
App Server
HTML
Database
…is being decomposed
8
Middle Tier
Data Tierdatabase
Client
Server
Data
JSON / XML JSON / XML
Presentation TierPresentation Tier
…is being decomposed
9
Middle Tier
Data Tierdatabase
Client
Server
Data
JSON / XML JSON / XML JSON / XML
Presentation TierPresentation Tier 3rd party Apps
…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
Platform Shift
Traditional Application Environments
Application
Database
Web/App Server
Operating System
Platform Shift
New Application Environments
Application
Database
Web/App Server
Operating SystemIaaS
Application
PaaS
Technology Shift
Traditional Application Environments
Application
Database
Web Server
Operating System
Application
Business Logic
UI
Data
Security
Technology Shift
Newer Application Environments
Application
Database
Web Server
Operating System
Application
Business Logic
UI API
Data
Security
Integration
Technology Shift
Application Decomposition
Application
Business Logic
UI API
Data
Security
Integration
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
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
GREAT APIS
A GREAT API IS … USER FRIENDLY
What does the user want?
How do they want it?
Sidebar: REST is awesome!
5 interaction patterns to consider
choose the right one for the job
#1: CRUD + Actions
CreateRead
UpdateDelete
…Execute
POST /widgetsGET /widgetsGET /widgets?name=FooGET /widgets/123PUT /widgets/123DELETE /widgets/123
POST /widgets/123/execute
#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
#2: Batch
Bulk Load
Get Job Status
POST /jobs[ { widget1 }, {widget2}, … ]
200 OKLocation /jobs/123
GET /jobs/123
[ status1, status2, status3, etc ]
#3: Streaming
Client APILong poll
Async events
#4:
• Instant notification for the web!• Example:– Client creates an invoice– Freshbooks calls HTTP webhook to synchronize
invoice to Salesforce
#5: Async
1.Send message POST /messages { … }
201 Received Location /messages/123
2. Check Status
GET /messages/123
A GREAT API IS … CORRECT*
* Except when it shouldn’t be
Details matter
Dates & Timezones
Error 500
GET
Hypertext
Content-Types
Stateful
Data modeling Pagination
Partial responses
Data TypesOrganizationServiceStub.AttributeCollection updateCollection = new OrganizationServiceStub.AttributeCollection();
OrganizationServiceStub.KeyValuePairOfstringanyType telephone = new OrganizationServiceStub.KeyValuePairOfstringanyType();telephone.setKey("telephone1");telephone.setValue("425-555-1212");
updateCollection.addKeyValuePairOfstringanyType(telephone);
Dates
{ createdAt : 124059811 …}
Dates
{ createdAt : “2008-03-01T13:00:00Z” …}
GET
GET /api/contacts/delete
200 OK
GET
DELETE /api/contacts/123
200 OK
Hypertext
GET /api/contacts
200 OK[ { “id” : “123” }]
Hypertext
GET /api/contacts
200 OK[ { “href” : “/api/contacts/123” “pictureHref” : “/api/contacts/123/johndoe.jpg” }]
A GREAT API IS … SECURE
• A GREAT API IS…SECURE
Do you think you’re special?
“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)
Basic Auth + SSL
• Easy• Accessible• Not great for public APIs…
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
WS-Security
A GREAT API IS … DOCUMENTED
• TODO: screenshots– Amazon
• Magento
• Apiary
A GREAT API IS … VERSIONED
POST /api/v1/foo
POST /api/1.0/foo
POST /api/2012-01-01/foo
POST /api/foo?v=2012-01-01
POST /api/fooVersion: 1.0
POST /api/fooContent-Type: application/vnd.foo+json;v=1.0
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?
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
A GREAT API … FAILS GRACEFULLY
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 #)
POST /foo{ … bad data … }
200 OK{ “message” : “Invalid request”}
POST /foo{ … bad data … }
400 Bad RequestContent-Length: 0
Good
POST /foo{ … bad data … }
400 Bad Request{ “message” : “The field foo123 is not allowed on the request.”}
Good
POST /contacts{ “name” : “Dan Diephouse” }
409 Contact Exists{ “message” : “A contact with that name already exists.”}
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”}
A Great API
• User friendly• “Correct”• Secure• Documented• Versioned• Fails Gracefully
Questions?
@dandiepdan.diephouse@mulesoft.com
top related