Your SlideShare is downloading. ×
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.

Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply



Published on

1 Like
  • Be the first to comment

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

No notes for slide


  • 1. BP209 In The Land Of Social Apps The API Is King Mikkel Flindt Heisterberg | Senior Solution Architect, Intravision Ryan Baxter | Software Engineer, IBM© 2013 IBM Corporation
  • 2. Please note IBM’s statements regarding its plans, directions, and intent are subject to change or withdrawal without notice at IBM’s sole discretion. Information regarding potential future products is intended to outline our general product direction and it should not be relied on in making a purchasing decision. The information mentioned regarding potential future products is not a commitment, promise, or legal obligation to deliver any material, code or functionality. Information about potential future products may not be incorporated into any contract. The development, release, and timing of any future features or functionality described for our products remains at our sole discretion. Performance is based on measurements and projections using standard IBM benchmarks in a controlled environment. The actual throughput or performance that any user will experience will vary depending upon many factors, including considerations such as the amount of multiprogramming in the users job stream, the I/O configuration, the storage configuration, and the workload processed. Therefore, no assurance can be given that an individual user will achieve results similar to those stated here.2 © 2013 IBM Corporation
  • 3. About us  Mikkel Flindt Heisterberg - @lekkim ─ With IntraVision, makers of the OnTime Group Calendar – were in the showcase ─ IBM Champion ─ Design Partner for Notes and IBM Connections ─ Enjoys coming to the US (Sam Adams, diet root beer, chocolate glazed donuts...)   Ryan Baxter - @ryanjbaxter ─ Software Engineer, IBM ─ Developer for IBM Notes ─ Lead developer for Notes Client Java UI APIs ─ OpenSocial Foundation Member and Apache Shindig committer ─ Enjoys building apps! ─ ─3 © 2013 IBM Corporation
  • 4. Credit IBM® Notes® Social Edition IBM® Domino® Social Edition IBM® iNotes® Social Edtion IBM® Connections® IBM® Social Business Toolkit IBM® WebSphere® Application Server (WAS)4 © 2013 IBM Corporation
  • 5. API == Application Programming Interface5 © 2013 IBM Corporation
  • 6. Agenda Whats an API to you? Why Build APIs? Good APIs vs. Bad APIs Internal vs. External API Versioning Authentication and Authorization Lessons Learned From Building APIs Developer Resources Q&A ─6 © 2013 IBM Corporation
  • 7. Whats an API to you? “API” can mean different things to different people In this presentation when we talk about APIs they can be a ─ Data API An API with the purpose of making it easier to interact with some thing e.g. the IBM Social Business Toolkit making it easier to interact with the activity stream. ─ Wrapper API A wrapper API (or “facade”) is for making a low level API easier to use and easier to grasp. Examples could be the IBM Social Business Toolkit JavaScript API (wraps, among other things, the IBM Connections REST API) or Dojo that, among other things, makes the DOM easier to work with and reduces boilerplate JavaScript. ─ UI API A special case of wrapper API to help you build UIs by providing a UI abstraction. Most APIs will actually consists of more than one part – when you define an API it will probably have a “data piece” and a “wrapper piece” i.e. a piece on the server and a piece to make it easier to use the data API from, say, a JavaScript library.7 © 2013 IBM Corporation
  • 8. 8 © 2013 IBM Corporation
  • 9. Why Build APIs? The number one reason to build APIs is to provide a service to your users ─ Users may be customers, partners, or even other developers on your team ─ The goal should be to enable use cases that would be impossible or difficult to achieve without the API APIs are all about value ─ What is valuable to your users? – Your data – A service you provide – A mashup – Your users / customers Define metrics to measure the success of your API ─ How does it help the business, your partners, your customers? Tighter integration into the applications your users are using today ─ Sidebar apps in Connections, Notes, iNotes ─ Embedded Experiences, Widgets, Dashboards, etc.9 © 2013 IBM Corporation
  • 10. Most Used APIs (2012) Mapping Social Search Photos Shopping Video Music Telephony Internet Messaging Source: Programmable Web 201210 © 2013 IBM Corporation
  • 11. Social API Growth 500 450 400 350 300 250 200 150 100 50 0 2005 2006 2007 2008 2009 2010 2011 2012 Source: Programmable Web11 © 2013 IBM Corporation
  • 12. Designing Good APIs  Planning is the key to the success of any API ─ Define the use cases for the API. What are you going to enable? ─ If you dont plan your end up with a confusing, unusable API set which provides NO value to anyone ─  What protocol(s) are you going to use? ─ REST, SOAP, JavaScript, ATOM, etc ─  What data model(s) are you going to use? ─ JSON, XML, CSV, Text, etc ─  Dont try and support everything! Start with what what makes sense for your consumers   Be consistent and intuitive with your APIs ─ 12 © 2013 IBM Corporation
  • 13. Which API would you prefer to call?SOAP RESTPOST /InStock HTTP/1.1 GET /rest/stockprice/ibm HTTP/1.1Host: Host: www.example.comContent-Type: application/soap+xml; charset=utf-8Content-Length: nnn<?xml version="1.0"?><soap:Envelopexmlns:soap="" soap:encodingStyle=""> <soap:Body xmlns:m=""> <m:GetStockPrice> <m:StockName>IBM</m:StockName> </m:GetStockPrice></soap:Body></soap:Envelope> 13 © 2013 IBM Corporation
  • 14. XML or JSON which one do I choose?XML JSON<person {xmlns=""> "id" : "1234", <id>1234</id> "displayName" : "Janey", "name" : {"formatted" : "Jane Doe"} <displayName>Janey</displayName> } <name> <formatted>Jane Doe</formatted> </name></person>14 © 2013 IBM Corporation
  • 15. Language Support15 © 2013 IBM Corporation
  • 16. “My users are not developers!”  You dont need to be providing a service to everyone in order to have an API.... the term “users” is vague intentionally :)   Your users may be other developers on your team dont you think they like APIs too?   Components within an app may have APIs which allow them to evolve independently of other internal consumers   If you decide to open the API up to a wider audience later on you dont have to do a bunch of work 16 © 2013 IBM Corporation
  • 17. Supporting Your API  What good is an API if you cant figure out how to use it?  TTFHW ─ “Time to first hello world” ─ If it takes to long to get to hello world your API is going to fail  Samples, Samples, Samples! ─ Code samples are a must, developers dont read documentation they write code! ─ Make them simple and strait forward so developers can easily understand what is happening  Tooling ─ Debuggers, playgrounds, explorers, dashboards, etc ─ With tooling the TTFHW decreases drastically  Community ─ Engage the community of developers using your APIs ─ You cannot scale to support the API but the community does scale ─ Gives new comers the impression that the API is useful and that they can find help when they need it17 © 2013 IBM Corporation
  • 18. Googles OAuth 2 Playground & API Explorer18 © 2013 IBM Corporation
  • 19. HTML 5 Playground19 © 2013 IBM Corporation
  • 20. IBM Social Business Toolkit Playground © 2013 IBM Corporation
  • 21. Playtime  Demo SBT Playgroup  Maybe demo OnTime API Explorer21 © 2013 IBM Corporation
  • 22. API Versioning Some of the changes that will occur are Your API ● ● Input requirements changing (new requirements, new meaning) will Input format changing (plain text to JSON, supporting change... ● multiple input formats) ● Output format changing (plain text to JSON, new structure) Even though ● Once an API is public and consumed you have to handle change you say it ● The key is designing for change – if youre wont – it ● providing a JavaScript library allow the caller to specify the version he/she depends on in the URL ( will! to avoid your updates breaking applications their application ● providing a data API allow the caller to use a versioned endpoint or allow the caller to specify the version they rely on “out of band” e.g. in a HTTP header22 © 2013 IBM Corporation
  • 23. API Versioning for non-public APIs Yeah – its all good with all that talk of change management but my API is not public – its only me using it! Well okay – but you probably have more than one client / app and will they all be updated simultaneously? Probably not. Fine... But I only have the one app and its never going to Well in 6 months youll need change! another app that use the same API but the data format requirements are different. So its just good sense to design for change.23 © 2013 IBM Corporation
  • 24. Security as it pertains to APIs  Deciding how to handle security is a key design point   Ask yourself questions like “is authentication always feasible?” or “should there be some alternative way of authentication?” ─ Relying on username / password is the easy choice but has its limitations as clients using your API may need to store it (on someones behalf) ─ How about (mobile) web apps – is it okay to have the user (re)authenticate? Do you need to support persistent authentication? ─ Do you need to be able to grant access without the user authenticating (i.e. a user being auto- authentication)  Decide on how to signal authentication and authorization errors up front ─ For HTTP based APIs you can use HTTP response codes or always return HTTP code 200 with a response message indicating success or failure ─ Other transports may need other mechanisms  24 © 2013 IBM Corporation
  • 25. Authentication and authorization  Securing the access to a resource or an API endpoint is made up of two parts 1) Making sure the user/process/program is who he/she/it says it is (proving identity) – we call this authentication 2) Making sure the user/process/program is allowed to work with, make calls against or operate on the data (proving access right) – we call this authorization ● Authentication can be done using a variety of mechanisms ● Username / password ● Certificates ● 3rd party trust e.g. SAML ● Ideally authentication should be external to the API and multiple approaches supported ● Authorization may either be declarative in the application container (external to application code) or be handled by the API (done in code) ● Declarative examples – Domino ACLs or Java EE role mapping ● ●25 © 2013 IBM Corporation
  • 26. Security in HTTP based APIs  The HTTP protocol has ways of indicating problems with authentication and authorization as response codes ─ 200 OK The request has succeeded. The information returned with the response is dependent on the method used in the request. ─ 401 Unauthorized The client MAY repeat the request with a suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. ─ 403 Forbidden The server understood the request, but is refusing to fulfill it Please note: This is an ─ 404 Not Found The server has not found anything matching the Request-URI. No interpretation of indication is given of whether the condition is temporary or permanent. the HTTP response codes – feel free to  If using Domino agents youre stuck with HTTP code 200 reject it... as the HTTP task handles the authentication and authorization before it reaches the agent  ─26 © 2013 IBM Corporation
  • 27. Example of HTTP code 200 for success and error{ APIBuild: 423, Status: “Error”, StatusNum: 24, StatusText: “Bummer! Not authorized”} { APIBuild: 423, Status: “OK”, StatusNum: 0, UsersInfo: { Status: “OK”, “StatusNum”: 0, ... } }27 © 2013 IBM Corporation
  • 28. Example of allowing auto and persistent authentication28 © 2013 IBM Corporation
  • 29. Authorization using OAuth  The standard used for Authorization is called OAuth ─ OAuth stands for open authorization NOT open authentication ─ Applications access users data via APIs on the behalf of the user NOT as the user ─ The most recent version of the OAuth is 2.0 although 1.0a is still widely used ─  In terms of OAuth your application or APIs will be protected by an OAuth provider ─ Developers using your API will go to the OAuth privider to register their application and receive an OAuth key and secret ─ The application using your APIs acts as the OAuth client ─  There are plenty of open source OAuth implementations available to use ─ Clients – XPages Social Enabler, IBM Social Business Toolkit, Notes, iNotes, Connections ─ Providers – IBM working on / investigating OAuth provider for Domino – OAuth provider on WAS 829 © 2013 IBM Corporation
  • 30. OAuth Flow API Request Request Browser Access Developer Do you want to allow Acme App access App to your data? Approval (OAuth client) YES NO Learning resource: “OAuth for Domino API Response Developers” by Julian Robichaux30 © 2013 IBM Corporation
  • 31. Lessons learned from building APIs  We started with a NRPC based API only ─ Lesson learned: From the get-go be prepared to support multiple endpoint types – now we also support HTTP  We accepted only plain text input ─ Lesson learned: Now were allowing the API user to both supply in the input in plain text (backwards compatibility) and in JSON as its easier for web clients.  We returned data in a proprietary array based format that resembled the representation on the server ─ Lesson learned: Too difficult to use and parse for clients and customers. Were now moving to be entirely JSON based to make the response easier to parse but were keeping the old format for backwards compatibility  We will only need to use our API from our own client UIs ─ Lesson learned: Not so much. Once we had the API the sky becamethe limit and were constantly coming up with new use cases and new ways to use the API. Being able to use the API over NRPC and HTTP was key. NRPC can also be own clients (plugins) but also agents, XPages and web services 31 © 2013 IBM Corporation
  • 32. Lessons learned from building APIs “Get my calendar data for this “Login to figure out who “I” am” Package command and talk to week sorted ascending by date” “Get my user id” server endpoint “Get calendar data for this week” “Sort appointments ascending by date” HTTP Delegates communication to transport transport High level Low level Notes Uses API API transport (“facade”) Notes transport (w/ session) Client application / request Client application / request32 © 2013 IBM Corporation
  • 33. Lessons learned from building APIs  Be prepared for failure, you wont get it right the first time! ─ Rewriting an API and implementation multiple times is common ─  Make your API flexible ─ You will never be able to predict all the use cases for your API ─ If you make your API flexible you will be able to adapt to new use cases as they come along ─  Make it easy for people to build apps using your API ─ If it is complicated to deploy people wont use it – I.E WAS + Connections + Domino + Sametime + Notes + iNotes ─ ─33 © 2013 IBM Corporation
  • 34. Resources  OAuth  “OAuth for the Domino Developer”Julian Robichaux  IBM Social Business Toolkit  Google Code Playground   Our blogs :) ─ Ryan: ─ Mikkel: ─34 © 2013 IBM Corporation
  • 35. Thats it! Hope you found it useful...35 © 2013 IBM Corporation
  • 36. Legal disclaimer © IBM Corporation 2013. All Rights Reserved. The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.36 © 2013 IBM Corporation