Bp209

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 user's 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 – we're 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

6. Agenda  What's 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. What's 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 UI's 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

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

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 don't 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 ─  Don't 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 REST POST /InStock HTTP/1.1 GET /rest/stockprice/ibm HTTP/1.1 Host: www.example.org Host: www.example.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: nnn <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap- encoding"> <soap:Body xmlns:m="http://www.example.org/stock"> <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="http://ns.opensocial.org/2008/opensocial"> "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

16. “My users are not developers!”  You don't 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 don't 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 don't have to do a bunch of work  16 © 2013 IBM Corporation

17. Supporting Your API  What good is an API if you can't 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 don't 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 it 17 © 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 you're wont – it ● providing a JavaScript library allow the caller to specify the version he/she depends on in the URL ( will! http://www.example.com/app.nsf/v1.7.2/library.js) 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 header 22 © 2013 IBM Corporation

23. API Versioning for non-public APIs Yeah – it's all good with all that talk of change management but my API is not public – it's 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 it's never going to Well in 6 months you'll need change! another app that use the same API but the data format requirements are different. So it's 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 someone's 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 API's 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 ACL's or Java EE role mapping ● ● 25 © 2013 IBM Corporation

26. Security in HTTP based API's  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 you're 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

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 8 29 © 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 Robichaux 30 © 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 we're allowing the API user to both supply in the input in plain text (backwards compatibility) and in JSON as it's 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. We're now moving to be entirely JSON based to make the response easier to parse but we're 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 we're 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 / request 32 © 2013 IBM Corporation

33. Lessons learned from building APIs  Be prepared for failure, you won't 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 won't use it – I.E WAS + Connections + Domino + Sametime + Notes + iNotes ─ ─ 33 © 2013 IBM Corporation

34. Resources  OAuth http://www.oauth.net  “OAuth for the Domino Developer”Julian Robichaux http://www.slideshare.net/dominopoint/dd12-oauth-for-domino-developers  IBM Social Business Toolkit http://www.ibm.com/developerworks/social/  Google Code Playground http://code.google.com/apis/ajax/playground/   Our blogs :) ─ Ryan: http://ryanjbaxter.com/ ─ Mikkel: http://lekkimworld.com ─ 34 © 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

Bp209

You are reading a preview.

Check these out next

Bp209

More Related Content

Slideshows for you (20)

Similar to Bp209 (20)

Bp209

Bp209

You are reading a preview.

Bp209

Recommended

More Related Content

Slideshows for you (20)

Similar to Bp209 (20)

Bp209