a great api is hard to find

Download A great api is hard to find

Post on 11-May-2015




0 download

Embed Size (px)


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

2. About Me 3. About MuleSoft Connect anything toeverything! Publish APIs Mediate services Integrate applications Load data Over 100K devcommunity 3200+ productiondeployments 4. The Impact of APIs 5. API Proliferation9000 4676 26471628 1116601 3521052005 2006 2007 2008 2009 2010 20112012Source: Programmable Web 6. API Billionaires Club 2011 Source: Programmable WebAll contents Copyright 62011, MuleSoft Inc. 7. The traditional 3-tier architecture ClientHTMLPresentation TierApp ServerMiddle TierDatabaseData Tier 7 8. is being decomposedPresentation Tier Presentation TierClient JSON / XML JSON / XMLMiddle Tier Server Data database Data Tier8 9. is being decomposedPresentation TierPresentation Tier 3rd party AppsClient JSON / XMLJSON / XML JSON / XML Middle TierServer Data databaseData Tier9 10. is being decomposedPresentation Tier Presentation Tier 3rd party AppsClient JSON / XML JSON / XML JSON / XMLMiddle TierServerAPIAPIAPIAPI APISaaS, Infrastructure Services,Data databaseAPISocial Media APIsAPI Data TierAPIAPIAPIAPI API10 11. Platform ShiftTraditional Application Environments Application Web/App ServerDatabaseOperating System 12. Platform ShiftNew Application EnvironmentsApplicationApplicationWeb/App ServerPaaS DatabaseIaaSOperating System 13. Technology ShiftTraditional Application EnvironmentsApplicationApplication UISecurity Database Business LogicWeb ServerOperating SystemData 14. Technology ShiftNewer Application EnvironmentsApplicationApplicationSecurityUIAPI Database Business LogicWeb ServerOperating SystemDataIntegration 15. Technology ShiftApplication DecompositionApplicationSecurityUIAPI Business LogicDataIntegration 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 modelsBuild an eco-system ofintegrations whichprovide more value to CRMyour customersMobileERPs YourPlethora of businessmodels fremium, payeCommerceAPI Marketingfor use, tiers, etcHRM 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 considerchoose the right one for the job 23. #1: CRUD + ActionsCreatePOST /widgets Read GET /widgetsGET /widgets?name=FooGET /widgets/123UpdatePUT /widgets/123 Delete DELETE /widgets/123 Execute POST /widgets/123/execute 24. #2: Batch Web architects must understand that resourcesare just consistent mappings from an identifier tosome set of views on server-side state. If one viewdoesnt suit your needs, then feel free to create adifferent resource that provides a better view (for any definition of better). These views need not have anything to do with how the information isstored on the server, or even what kind of state it ultimately reflects. It just needs to beunderstandable (and actionable) by the recipient.- Fielding 25. #2: BatchBulk LoadPOST /jobs * , widget1 -, ,widget2-, + 200 OK Location /jobs/123Get Job Status GET /jobs/123 [ status1, status2, status3, etc ] 26. #3: Streaming Long pollClientAPI Async events 27. #4: Instant notification for the web! Example: Client creates an invoice Freshbooks calls HTTP webhook to synchronizeinvoice to Salesforce 28. #5: Async1. Send messagePOST /messages{ } 201 Received Location /messages/1232. Check StatusGET /messages/123 29. A GREAT API IS CORRECT** Except when it shouldnt be 30. Partial responsesDates & TimezonesHypertext StatefulDetails matterError 500 Content-TypesGET Pagination Data modeling 31. Data TypesOrganizationServiceStub.AttributeCollection updateCollection =new OrganizationServiceStub.AttributeCollection();OrganizationServiceStub.KeyValuePairOfstringanyType telephone = new OrganizationServiceStub.KeyValuePairOfstringanyType();telephone.setKey("telephone1");telephone.setValue("425-555-1212");updateCollection.addKeyValuePairOfstringanyType(telephone); 32. Dates{createdAt : 124059811} 33. Dates{createdAt : 2008-03-01T13:00:00Z} 34. GETGET /api/contacts/delete200 OK 35. GETDELETE /api/contacts/123200 OK 36. HypertextGET /api/contacts200 OK[{id : 123}] 37. HypertextGET /api/contacts200 OK[ { href : /api/contacts/123 pictureHref : /api/contacts/123/johndoe.jpg }] 38. A GREAT API IS SECURE A GREAT API ISSECURE 39. Do you think youre special? 40. Special Companies Normal Companies Microsoft (WS- Salesforce (OAuth 2 or BasicSecurity/Policy + Live ID Auth*)variant) Twitter (OAuth 1) QuickBooks (SAML/OAuth Facebook (OAuth 2)variation) AWS (Custom encryption) 41. Basic Auth + SSL Easy Accessible Not great for public APIs 42. 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 43. WS-Security 44. A GREAT API IS DOCUMENTED 45. TODO: screenshots Amazon 46. Magento 47. Apiary 48. A GREAT API IS VERSIONED 49. POST /api/v1/foo 50. POST /api/1.0/foo 51. POST /api/2012-01-01/foo 52. POST /api/foo?v=2012-01-01 53. POST /api/fooVersion: 1.0 54. POST /api/fooContent-Type: application/vnd.foo+json;v=1.0 55. 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? 56. Which approachHeader URL Potentially more correct Easier to hack in theHATEOS approachbrowser & with curl Provides clarity when there are structural changes e.g. its clear that resource/foo went away in version 2 57. A GREAT API FAILS GRACEFULLY 58. A great error has1. A machine understandable HTTP status code2. An end user message3. If relevant, details for the developer to escalate the issue (tracking #) 59. POST /foo{ bad data }200 OK{message : Invalid request} 60. POST /foo{ bad data }400 Bad RequestContent-Length: 0 61. GoodPOST /foo{ bad data }400 Bad Request{message : The field foo123is not allowed on the request.} 62. GoodPOST /contacts{ name : Dan Diephouse }409 Contact Exists{message : A contact withthat name already exists.} 63. GoodPOST /contacts{ name : Dan Diephouse }500 Error{message : We were not able to processyoure request due to an unexpected error.Please contact support for help in resolvingthis request (Request ID 19022334).requestId : 19022334time : 2012-03-01T13:00:00Z} 64. A Great API User friendly Correct Secure Documented Versioned Fails Gracefully 65. Questions? @dandiepdan.diephouse@mulesoft.com