a great api is hard to find
TRANSCRIPT
![Page 1: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/1.jpg)
A Great API is Hard to Find
Dan DiephouseMuleSoft
@dandiep
![Page 2: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/2.jpg)
About Me
![Page 3: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/3.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/4.jpg)
The Impact of APIs
![Page 5: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/5.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/6.jpg)
All contents Copyright © 2011, MuleSoft Inc.
6
API Billionaires Club 2011
Source: Programmable Web
![Page 7: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/7.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/8.jpg)
…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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/9.jpg)
…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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/10.jpg)
…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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/11.jpg)
Platform Shift
Traditional Application Environments
Application
Database
Web/App Server
Operating System
![Page 12: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/12.jpg)
Platform Shift
New Application Environments
Application
Database
Web/App Server
Operating SystemIaaS
Application
PaaS
![Page 13: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/13.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/14.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/15.jpg)
Technology Shift
Application Decomposition
Application
Business Logic
UI API
Data
Security
Integration
![Page 16: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/16.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/17.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/18.jpg)
GREAT APIS
![Page 19: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/19.jpg)
A GREAT API IS … USER FRIENDLY
![Page 20: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/20.jpg)
What does the user want?
How do they want it?
![Page 21: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/21.jpg)
Sidebar: REST is awesome!
![Page 22: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/22.jpg)
5 interaction patterns to consider
choose the right one for the job
![Page 23: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/23.jpg)
#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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/24.jpg)
#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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/25.jpg)
#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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/26.jpg)
#3: Streaming
Client APILong poll
Async events
![Page 27: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/27.jpg)
#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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/28.jpg)
![Page 29: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/29.jpg)
#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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/30.jpg)
A GREAT API IS … CORRECT*
* Except when it shouldn’t be
![Page 31: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/31.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/32.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/33.jpg)
Dates
{ createdAt : 124059811 …}
![Page 34: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/34.jpg)
Dates
{ createdAt : “2008-03-01T13:00:00Z” …}
![Page 35: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/35.jpg)
GET
GET /api/contacts/delete
200 OK
![Page 36: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/36.jpg)
GET
DELETE /api/contacts/123
200 OK
![Page 37: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/37.jpg)
Hypertext
GET /api/contacts
200 OK[ { “id” : “123” }]
![Page 38: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/38.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/39.jpg)
A GREAT API IS … SECURE
• A GREAT API IS…SECURE
![Page 40: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/40.jpg)
Do you think you’re special?
![Page 41: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/41.jpg)
“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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/42.jpg)
Basic Auth + SSL
• Easy• Accessible• Not great for public APIs…
![Page 43: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/43.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/44.jpg)
WS-Security
![Page 45: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/45.jpg)
A GREAT API IS … DOCUMENTED
![Page 46: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/46.jpg)
• TODO: screenshots– Amazon
![Page 47: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/47.jpg)
• Magento
![Page 48: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/48.jpg)
• Apiary
![Page 49: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/49.jpg)
![Page 50: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/50.jpg)
A GREAT API IS … VERSIONED
![Page 51: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/51.jpg)
POST /api/v1/foo
![Page 52: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/52.jpg)
POST /api/1.0/foo
![Page 53: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/53.jpg)
POST /api/2012-01-01/foo
![Page 54: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/54.jpg)
POST /api/foo?v=2012-01-01
![Page 55: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/55.jpg)
POST /api/fooVersion: 1.0
![Page 56: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/56.jpg)
POST /api/fooContent-Type: application/vnd.foo+json;v=1.0
![Page 57: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/57.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/58.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/59.jpg)
A GREAT API … FAILS GRACEFULLY
![Page 60: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/60.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/61.jpg)
POST /foo{ … bad data … }
200 OK{ “message” : “Invalid request”}
![Page 62: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/62.jpg)
POST /foo{ … bad data … }
400 Bad RequestContent-Length: 0
![Page 63: A great api is hard to find](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/63.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/64.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/65.jpg)
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](https://reader035.vdocument.in/reader035/viewer/2022062513/554fb2a1b4c90586258b524f/html5/thumbnails/66.jpg)
A Great API
• User friendly• “Correct”• Secure• Documented• Versioned• Fails Gracefully