An API needs to be user friendly, secure, documented, versioned, and handle failures gracefully to be considered great. The document discusses how APIs have evolved from monolithic applications to microservices that decompose functionality. It also covers best practices for API design like using RESTful principles, supporting different interaction patterns, handling dates and errors properly, and using authentication standards like OAuth. Versioning approaches and ensuring APIs are well documented and fail gracefully are also emphasized as important characteristics of a great API.

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

2. About Me

3. About MuleSoft
• Connect anything to
everything!
• Publish APIs
• Mediate services
• Integrate applications
• Load data
• Over 100K dev
community
• 3200+ production
deployments

4. The Impact of APIs

5. API Proliferation
9000
4676
2647
1628
1116
601
352
105
2005 2006 2007 2008 2009 2010 2011 2012
Source: Programmable Web

6. API Billionaires Club 2011
Source: Programmable Web
All contents Copyright ©
6
2011, MuleSoft Inc.

7. The traditional 3-tier architecture
Client
HTML
Presentation Tier
App Server
Middle Tier
Database
Data Tier
7

8. …is being decomposed
Presentation Tier Presentation Tier Client
JSON / XML JSON / XML
Middle Tier Server
Data
database Data Tier
8

9. …is being decomposed
Presentation Tier Presentation Tier 3rd party Apps Client
JSON / XML JSON / XML JSON / XML
Middle Tier Server
Data
database Data Tier
9

10. …is being decomposed
Presentation Tier Presentation Tier 3rd party Apps Client
JSON / XML JSON / XML JSON / XML
Middle Tier Server
API API API
API API
SaaS, Infrastructure Services, Data
database
API
Social Media APIs API Data Tier
API API
API API
API
10

11. Platform Shift
Traditional Application Environments
Application
Web/App Server
Database
Operating System

12. Platform Shift
New Application Environments
Application Application
Web/App Server PaaS
Database
IaaS
Operating System

13. Technology Shift
Traditional Application Environments
Application
Application
UI
Security
Database
Business Logic
Web Server
Operating System Data

14. Technology Shift
Newer Application Environments
Application
Application
Security
UI API
Database
Business Logic
Web Server
Operating System Data Integration

15. Technology Shift
Application Decomposition
Application
Security
UI API
Business Logic
Data Integration

16. 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

17. Changing business models
Build an eco-system of
integrations which
provide more value to CRM
your customers Mobile ERPs
Your
Plethora of business
models – fremium, pay eCommerce
API Marketing
for use, tiers, etc
HRM

18. GREAT APIS

19. A GREAT API IS … USER FRIENDLY

20. What does the user want?
How do they want it?

21. Sidebar: REST is awesome!

22. 5 interaction patterns to consider
choose the right one for the job

23. #1: CRUD + Actions
Create POST /widgets
Read GET /widgets
GET /widgets?name=Foo
GET /widgets/123
Update PUT /widgets/123
Delete DELETE /widgets/123
…
Execute POST /widgets/123/execute

24. #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

25. #2: Batch
Bulk Load POST /jobs
* , widget1 -, ,widget2-, … +
200 OK
Location /jobs/123
Get Job Status GET /jobs/123
[ status1, status2, status3, etc ]

26. #3: Streaming
Long poll
Client API
Async events

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

29. #5: Async
1. Send message
POST /messages
{ … }
201 Received
Location /messages/123
2. Check Status
GET /messages/123

30. A GREAT API IS … CORRECT*
* Except when it shouldn’t be

31. Partial responses
Dates & Timezones
Hypertext
Stateful
Details matter
Error 500 Content-Types
GET Pagination
Data modeling

32. Data Types
OrganizationServiceStub.AttributeCollection updateCollection =
new OrganizationServiceStub.AttributeCollection();
OrganizationServiceStub.KeyValuePairOfstringanyType telephone =
new OrganizationServiceStub.KeyValuePairOfstringanyType();
telephone.setKey("telephone1");
telephone.setValue("425-555-1212");
updateCollection.addKeyValuePairOfstringanyType(telephone);

33. Dates
{
createdAt : 124059811
…
}

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

35. GET
GET /api/contacts/delete
200 OK

36. GET
DELETE /api/contacts/123
200 OK

37. Hypertext
GET /api/contacts
200 OK
[
{
“id” : “123”
}
]

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

39. A GREAT API IS … SECURE
• A GREAT API IS…SECURE

40. Do you think you’re special?

41. “Special” Companies Normal Companies
• Microsoft (WS- • Salesforce (OAuth 2 or Basic
Security/Policy + Live ID Auth*)
variant) • Twitter (OAuth 1)
• QuickBooks (SAML/OAuth • Facebook (OAuth 2)
variation)
• AWS (Custom encryption)

42. Basic Auth + SSL
• Easy
• Accessible
• Not great for public APIs…

43. 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

44. WS-Security

45. A GREAT API IS … DOCUMENTED

46. • TODO: screenshots
– Amazon

47. • Magento

48. • Apiary

50. A GREAT API IS … VERSIONED

51. POST /api/v1/foo

52. POST /api/1.0/foo

53. POST /api/2012-01-01/foo

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

55. POST /api/foo
Version: 1.0

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

57. 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?

58. Which approach
Header URL
• Potentially more “correct” • Easier to hack in the
HATEOS approach browser & with curl
• Provides clarity when there
are structural changes
– e.g. it’s clear that resource
/foo went away in version 2

59. A GREAT API … FAILS GRACEFULLY

60. A great error has
1. A machine understandable HTTP status code
2. An end user message
3. If relevant, details for the developer to
escalate the issue (tracking #)

61. POST /foo
{ … bad data … }
200 OK
{
“message” : “Invalid request”
}

62. POST /foo
{ … bad data … }
400 Bad Request
Content-Length: 0

63. Good
POST /foo
{ … bad data … }
400 Bad Request
{
“message” : “The field foo123
is not allowed on the request.”
}

64. Good
POST /contacts
{ “name” : “Dan Diephouse” }
409 Contact Exists
{
“message” : “A contact with
that name already exists.”
}

65. 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”
}

66. A Great API
• User friendly
• “Correct”
• Secure
• Documented
• Versioned
• Fails Gracefully

67. Questions?
@dandiep
dan.diephouse@mulesoft.com