A great api is hard to find


Published on

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Thanks for inviting me.Background in integration I live in San FranciscoI love wineI play the accordionI love building products and products need APIs.Currently focused on the problem of connecting everything together – how do we make it as simple as possible? How do we break down cloud silos?
  • Let’s talk about the impact of APIs and I don’t mean all the schwag we see around this conference. Look around, all these companies are focusing on APIs. It’s not just developers anymore, it’s everyone.How many of you integrate with more than one API?
  • Center of gravity shifting to the cloudRise of the composite appLess visibility and controlRapid innovation means middleware must adapt and support change
  • We’ll start around the early 2000s, where the traditional application looked something .HTML rendered by serverData tier maintained by db admins, run on premise
  • Presentation tier moves to client side – AJAX (Backbone, Ext, Sencha, Jquery, etc) and Mobile (iPhone, Android)Expectation now from consumers that you have a mobile appForces a shift – everything now has a REST API
  • People DEMAND an API and your business wants to monetize it Look at all the companies here around this…
  • Correspondingly, you want to use everyone else’s APIsYour application is no longer a database, it’s a composite application based on a number of different infrastructure services, social media APIs, etc
  • Simultaneously there is a platform shift, we’re moving from the 3 tier server to PaaS and IaaSHow many here deploy their applications on Heroku?
  • Building it themselves
  • Data is still important, but integration to external services is becoming just as important. Is all your data in the database? Or do you have it spread out over different services/datastore? There is no one DB to rule them all for example
  • Building it themselves
  • Building it themselves
  • The worst APIs are the ones that were designed without any thought. The ones that just expose whatever at random. They don’t worry about the how and why, but as any user knows, that’s the most important part.
  • This talk presupposes that REST is the way to go, so I figure I better say a few words on that. I really go to REST+JSON by default. You have to make a strong argument with me to go another way. I’m sure you know by now – REST stands for Representation State transfer. The simple way to explain it is that you have a set of nouns (widgets) and fixed set of verbs. REST has so many good things going for it-it is the language of the webit is scalableit is easy to get started – you just hit the URL in the browser or with Curl. No complicated libraries. You can also take it in pieces. it is universalit is evolvable – we can use URIs and data formats to build up a set of nouns The only thing about REST that is not great is that people easily screw it up. I’m sure people will say the same thing about me – because I’m advocating a kind of REST-lite approach. but as long as you’re concious of the downsides of leaving other stuff behind, you can do it.I think the market is bearing this out as well in terms of what we’re seeing from vendors and the services they produce.
  • Choose your nouns, not your verbs.For things that don’t fit, then put the action in the URI
  • A great API supports batch if your users need it. Don’t make people hit your API a million times to import a million rows.While there is also HTTP pipelineing, it has a couple challengeserrors returned in same order, which can add latencynot well supported by client libraries
  • I call this streaming because this is what Salesforce calls it, but by it I simply mean pub sub over HTTP-It gives up some of the advantages of REST (statefulness), but it gives you real time updates and reduces the # of requests the client needs to make-Difficult to implement for consumers as it’s uncommon-
  • “so simple you’ll think it’s stupid”
  • I can’t make you to write beautiful code, but I can try! So I will highlight a few problems if you don’t implement stuff correctly
  • MS Dynamics CRMno thought to data structuresTried to do a schemaless design in a schema – XML schema just deal well with that. Ended up with Arrayofstringtype and so on-would be better off with a schemaless JSON based design
  • Timezones!
  • Timezones!
  • Make your application hypertext. Then users can browse to different resources
  • AWS I will give a little bit of slack because pre-date everything – and at least it’s consistent and easy.
  • OAuth allows you to build an authentication mechanism which allows applications to act, not just usersIt is much more secure for 3rd party applications because you can track turn off access for invididual applications.
  • If anything use XML encryption. I completely get that there are valid use cases that WS-Security meets that other specs don’t, but crikey, it’s impossible for people to use, so don’t expect your API to catch on with it.
  • A great api is hard to find

    1. 1. A Great API is Hard to Find Dan Diephouse MuleSoft @dandiep
    2. 2. About Me
    3. 3. About MuleSoft• Connect anything to everything!• Publish APIs• Mediate services• Integrate applications• Load data• Over 100K dev community• 3200+ production deployments
    4. 4. The Impact of APIs
    5. 5. API Proliferation 9000 4676 2647 1628 1116 601 3521052005 2006 2007 2008 2009 2010 2011 2012 Source: Programmable Web
    6. 6. API Billionaires Club 2011 Source: Programmable WebAll contents Copyright © 62011, MuleSoft Inc.
    7. 7. The traditional 3-tier architecture Client HTML Presentation Tier App Server Middle Tier Database Data Tier 7
    8. 8. …is being decomposedPresentation Tier Presentation Tier Client JSON / XML JSON / XML Middle Tier Server Data database Data Tier 8
    9. 9. …is being decomposedPresentation Tier Presentation Tier 3rd party Apps Client JSON / XML JSON / XML JSON / XML Middle Tier Server Data database Data Tier 9
    10. 10. …is being decomposedPresentation 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. 11. Platform ShiftTraditional Application Environments Application Web/App Server Database Operating System
    12. 12. Platform ShiftNew Application Environments Application Application Web/App Server PaaS Database IaaS Operating System
    13. 13. Technology ShiftTraditional Application Environments Application Application UI Security Database Business Logic Web Server Operating System Data
    14. 14. Technology ShiftNewer Application Environments Application Application Security UI API Database Business Logic Web Server Operating System Data Integration
    15. 15. Technology ShiftApplication DecompositionApplication Security UI API Business Logic Data Integration
    16. 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. 17. Changing business modelsBuild an eco-system ofintegrations whichprovide more value to CRMyour customers Mobile ERPs YourPlethora of businessmodels – fremium, pay eCommerce API Marketingfor use, tiers, etc HRM
    18. 18. GREAT APIS
    20. 20. What does the user want? How do they want it?
    21. 21. Sidebar: REST is awesome!
    22. 22. 5 interaction patterns to considerchoose the right one for the job
    23. 23. #1: CRUD + ActionsCreate POST /widgets Read GET /widgets GET /widgets?name=Foo GET /widgets/123Update PUT /widgets/123 Delete DELETE /widgets/123 …Execute POST /widgets/123/execute
    24. 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 viewdoesn’t 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. 25. #2: Batch Bulk Load POST /jobs * , widget1 -, ,widget2-, … + 200 OK Location /jobs/123Get Job Status GET /jobs/123 [ status1, status2, status3, etc ]
    26. 26. #3: Streaming Long pollClient API Async events
    27. 27. #4:• Instant notification for the web!• Example: – Client creates an invoice – Freshbooks calls HTTP webhook to synchronize invoice to Salesforce
    28. 28. #5: Async1. Send message POST /messages { … } 201 Received Location /messages/1232. Check Status GET /messages/123
    29. 29. A GREAT API IS … CORRECT** Except when it shouldn’t be
    30. 30. Partial responses Dates & Timezones Hypertext Stateful Details matterError 500 Content-Types GET Pagination Data modeling
    31. 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. 32. Dates{ createdAt : 124059811 …}
    33. 33. Dates{ createdAt : “2008-03-01T13:00:00Z” …}
    34. 34. GETGET /api/contacts/delete200 OK
    35. 35. GETDELETE /api/contacts/123200 OK
    36. 36. HypertextGET /api/contacts200 OK[ { “id” : “123” }]
    37. 37. HypertextGET /api/contacts200 OK[ { “href” : “/api/contacts/123” “pictureHref” : “/api/contacts/123/johndoe.jpg” }]
    39. 39. Do you think you’re special?
    40. 40. “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)
    41. 41. Basic Auth + SSL• Easy• Accessible• Not great for public APIs…
    42. 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. 43. WS-Security
    45. 45. • TODO: screenshots – Amazon
    46. 46. • Magento
    47. 47. • Apiary
    49. 49. POST /api/v1/foo
    50. 50. POST /api/1.0/foo
    51. 51. POST /api/2012-01-01/foo
    52. 52. POST /api/foo?v=2012-01-01
    53. 53. POST /api/fooVersion: 1.0
    54. 54. POST /api/fooContent-Type: application/vnd.foo+json;v=1.0
    55. 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. 56. Which approachHeader 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
    58. 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. 59. POST /foo{ … bad data … }200 OK{ “message” : “Invalid request”}
    60. 60. POST /foo{ … bad data … }400 Bad RequestContent-Length: 0
    61. 61. GoodPOST /foo{ … bad data … }400 Bad Request{ “message” : “The field foo123is not allowed on the request.”}
    62. 62. GoodPOST /contacts{ “name” : “Dan Diephouse” }409 Contact Exists{ “message” : “A contact withthat name already exists.”}
    63. 63. GoodPOST /contacts{ “name” : “Dan Diephouse” }500 Error{ “message” : “We were not able to processyou’re request due to an unexpected error.Please contact support for help in resolvingthis request (Request ID 19022334).” “requestId” : 19022334 “time” : “2012-03-01T13:00:00Z”}
    64. 64. A Great API• User friendly• “Correct”• Secure• Documented• Versioned• Fails Gracefully
    65. 65. Questions? @dandiepdan.diephouse@mulesoft.com