Recommended Practices for Designing a Web API

Web APIs are changing the way companies define and run their business, opening new channels and fostering innovation. This deck will present the key concepts of designing and implementing a web API. This will include how to decide if an API should be public or private, how to design a REST-based web API, how to design a mobile-friendly web API, how to implement caching, how to secure an API, and how to manage and advertise your API. Some examples of great public web APIs are also analyzed and demonstrated.

Transcript

1. © 2013 IBM Corporation Recommended Practices for Designing a Web API Alan Moore, Senior Technical Staff Member, AIM, SWG Dinesh Shetty, Senior Certified IT Specialist, ISSW 2372
2. 2 2 © 2013 IBM Corporation 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.
3. 3 3 © 2013 IBM Corporation Agenda •Key Concepts •API Exposures – Public? Private? Partner? •Design considerations for a REST-based Web API ‒ Walk through of an example application •Designing a mobile-friendly Web API •Implementing Caching for your API •API Security •Managing and advertizing your API
4. 4 4 © 2013 IBM Corporation Key Concepts – Terminologies, technologies & benefits •Web API ‒ A defined set of HTTP request and response message ‒ typically expressed in JSON or XML •Mashup ‒ A web application that uses Web APIs to combine data, presentation ‒ from two or more sources to create new services •Apps ‒ An application accessed over the Internet or an intranet. ‒ Coded in a browser-supported programming language (such as JavaScript and markup language like HTML) •Technologies for APIs ‒ REST Architectural style ‒ JSON, XML ‒ OAuth ‒ Basic Auth •Benefits of APIs ‒ Quicker, easier and more re- usable technical access to your enterprise assets ‒ Rapidly develop web, mobile and tablet applications from your organizations technical assets
5. 5 5 © 2013 IBM Corporation Key Concepts – Essentials for successful API •Follows REST best practices ‒ Learning from the popular APIs ‒ Facebook, Twitter, Google etc •Good meaningful and to-the-point reference documentation •Simple and important code samples •Author’s articles •Managed and open forum ‒ Encourage discussion ‒ Answer questions from API users •Automatic and easy sign-up or registration process ‒ Self service •Clear terms and conditions to follow •Comprehensive Entitlements & Pricing information
6. 6 6 © 2013 IBM Corporation 70% of Web APIs are REST; REST is simple Source: http://www.slideshare.net/jmusser/pw-glue-conmay2010 REST is an architectural style; not a standard
7. 7 7 © 2013 IBM Corporation API Exposures – Public? Private? Protected? 7
8. 8 8 © 2013 IBM Corporation A Little More Info on the Types Of API Exposures Public, Open- To-All APIs Protected, Open- To-Partner APIs Private, Open- To-Employee APIs • APIs are open to any developer who wants to sign up • Apps are more targeted towards end consumers • The business driver is to engage customers through external developers • APIs are open to select business partners • Apps could be targeted at end consumers or business users • The business driver is usually different, based on the data and type of business of the enterprise • APIs are exposed only to existing developers within the enterprise • Apps are usually targeted at employees of the enterprise • The business driver is more around productivity of employees
9. 9 9 © 2013 IBM Corporation Questions and Considerations •No “One rule fits all” recommendation – more of a business decision for an organization •Exposing a Public API ‒ You don’t want to expose all the capabilities of your system! ‒ Information Security – what data is shared? •ESBs, API Management solutions allow you to filter data – expose only required fields from a response •How much functionality is to be provided in an API? ‒ Organizations chose to provide limited, but important capability through APIs ‒ E.g. Comprehensive banking capabilities Vs. basic quick-use tasks •Both versions – Public and Private? ‒ Management overheads
10. 10 10 © 2013 IBM Corporation •Designing a REST-based Web API • Typical API developer requirements •Walkthrough • Sample Application 10
11. 11 11 © 2013 IBM Corporation Typical API developer requirements •Value to the application ‒ they will put up with a lot if there is high value to the application •Stability, stability, stability! ‒ API has to be up and responsive, otherwise consumers blame the app and won’t use it (they don’t care about the APIs that are used) ‒ Don’t break my app – Changes need to be additive, backwardly compatible ‒ Don’t change your OAuth logon - breaks the visibility in others apps •Listen to their feedback ‒ Facebook and Twitter APIs have vastly improved from their original APIs ‒ Quick sign up – don’t make me fill out a lot of forms and go back and forth ‒ Allow free trial usage - Let me try it and even better use it for free until I have a volume of customers ‒ Provide clear documentation - follow standards, provide clear doc, examples, SDK ‒ Make it easy for me to get help day or night (as I may be in a different timezone) – with forums, bug reporting, community tools, API status visibility etc •Show me my API usage, my users’ usage, my data
12. 12 12 © 2013 IBM Corporation Use Caching Architect your backend for scaling Leverage Asynchronous Messaging Use Compression Build on an Elastic Platform
13. 13 13 © 2013 IBM Corporation Accounts Contacts Opportunities Sample Application •Define collections ‒ Accounts ‒ Contacts ‒ Opportunities •Define Verbs ‒ GET (Equivalent to SQL SELECT) ‒ POST (Equivalent to SQL CREATE) ‒ PUT (Equivalent to SQL UPDATE) ‒ DELETE (Same connotation in SQL)
14. 14 14 © 2013 IBM Corporation Account REST API for Sample Application •GET /Accounts ‒ SELECT * FROM Accounts •GET /Accounts/{Id} ‒ SELECT * FROM Accounts WHERE Id = ? •GET /Accounts/{id}/Contacts ‒ SELECT C.* FROM Contacts C WHERE C.AccountId = ? •GET /Accounts/{id}/Opportunities ‒ SELECT O.* FROM Opportunities O WHERE O.AccountId = ?
15. 15 15 © 2013 IBM Corporation Contacts REST API for Sample Application •GET /Contacts ‒ SELECT * FROM Contacts •GET /Contacts/{Id} ‒ SELECT * FROM Contacts WHERE Id = ? •GET /Contacts/{id}/Accounts ‒ SELECT A.* FROM Accounts A, Contacts C WHERE C.Id = ? AND A.Id = C.AccountId •GET /Contacts/{id}/Opportunities ‒ SELECT O.* FROM Opportunities O WHERE O.ContactId = ?
16. 16 16 © 2013 IBM Corporation Opportunities REST API for Sample Application •GET /Opportunities ‒ SELECT * FROM Opportunities •GET /Opportunities/{Id} ‒ SELECT * FROM Opportunities WHERE Id = ? •GET /Opportunities/{id}/Accounts ‒ SELECT A.* FROM Accounts A, Opportunities O WHERE O.Id = ? AND A.Id = O.AccountId •GET /Opportunities/{id}/Contacts ‒ SELECT C.* FROM Opportunities O, Contacts C WHERE O.Id = ? AND O.ContactId = C.Id
17. 17 17 © 2013 IBM Corporation Delete REST Operations for Sample Application •DELETE /Accounts/{Id} ‒ DELETE FROM Accounts WHERE Id = ? •DELETE /Contacts/{Id} ‒ DELETE FROM Contacts WHERE Id = ? •DELETE /Opportunities/{Id} ‒ DELETE FROM Opportunities WHERE Id = ? •Depending on the relationships, some APIs may need to update the dependent objects to ensure referential integrity •E.g. A primary contact for an opportunity or account leaving the company
18. 18 18 © 2013 IBM Corporation Design a mobile-friendly Web API 18
19. 19 19 © 2013 IBM Corporation Key Mobility API Design considerations Key Constraints •Mobile devices run on low power; low bandwidth •Network quality is always changing – can be weak •User experience needs to be the best at all times Design Considerations •Keep your API complete; incomplete ones burden the App •Keep UI simple and fast •Most of the time API’s “get” data to be displayed – Start from the UI, not the data •Payloads ‒ Pay attention to consistency and correctness ‒ Ensure your API Payloads return relevant and required information ‒ Avoid HTML, CSS or JavaScript in responses ‒ Start with what you want to display, not the data •Data Aggregation ‒ Avoid overwhelming number of calls to different backends – your API will slow down if not ‒ Aggregation ideally done at the backend
20. 20 20 © 2013 IBM Corporation Key Mobility API Design considerations •Use Cache Control ‒ For responses that can be cached •What’s the best format for Mobile API? ‒ JSON – Growing in popularity; lightweight Natural and easy to use from JavaScript JavaScript is increasing in popularity for Web apps ‒ XML – Most APIs today use XML; more readable (but that’s a debate) More XML APIs registered on programmableweb than JSON XML continues to be leading choice of format for APIs ‒ Key: Keep your request and responses simple Think about pagination, limits when returning large set of results E.g. LinkedIn API – uses start and count parameters
21. 21 21 © 2013 IBM Corporation Implementing Caching for your API 21
22. 22 22 © 2013 IBM Corporation Implement Caching HTTP headers can contain caching directives HTTP/1.1 200 OK Date: Fri, 30 Oct 1998 13:19:41 GMT Server: Apache/1.3.3 (Unix) Cache-Control: max-age=3600, must-revalidate Expires: Fri, 30 Oct 1998 14:19:41 GMT Last-Modified: Mon, 29 Jun 1998 02:28:12 GMT ETag: "3e86-410-3596fbbc" Content-Length: 1040 Content-Type: text/html Caches improve network efficiency, improves scalability, and improves user-perceived performance of your API
23. 23 23 © 2013 IBM Corporation Securing your API 23
24. 24 24 © 2013 IBM Corporation Security mechanisms for Web APIs OAuth •Enables users to allow web applications to access other web applications on the user’s behalf Basic Auth •Passes Username and password with the request •Defined by the HTTP specification •Uses HTTP Header “Authorization” •Uses encoding, no encryption API Keys •Not based on any standard •Service Provider decides implementation •Keys act like signatures
25. 25 25 © 2013 IBM Corporation Security Mechanisms - OAuth “The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf” FourSquare Twitter Steve, logged on Foursquare, wants to update his holiday location and also post the same on his Twitter page Twitter provides an access token to Foursquare that provides access to Steve’s twitter page Forsquare uses access token provided by twitter to make a post on twitter on Steve’s behalf Access token (no user id/password) required
26. 26 26 © 2013 IBM Corporation Security Mechanisms - OAuth
27. 27 27 © 2013 IBM Corporation Basic Auth •Must use SSL if you opt for Basic Authentication ‒ Username and Password transmitted in clear text ‒ Base64 encoded, not encrypted •Pros ‒ Easy implementation task for clients Part of nearly every HTTP request library ‒ Simple Server setup Use existing BasicAuth credentials •Cons ‒ Username password is a must ‒ No default encryption of credentials ‒ Requires user name and password to be embedded in client code
28. 28 28 © 2013 IBM Corporation API Keys •By far the most popular mechanism followed by API Management solutions •Enables establishing identity of the invoking application - No key? No access •Enables metering, statistics and accounting – also chargeback •Implementation not based on any standard – API provider can have proprietary implementation •Basics ‒ Key is part of URL (how to is described in API documentation) ‒ For e.g. http://myapiprovider.com/api?appId=asf1231ssdfwrwe •Pros ‒ Easy key generation and distribution ‒ No username and password required in raw form •Cons ‒ Unsigned ‒ Must embed them in code ‒ Transmitted in plain text Best Practices •Use signed requests over unsigned •One key per application per developer •Require username in headers
29. 29 29 © 2013 IBM Corporation Managing and advertizing your APIs What needs management? How to manage? API and Resource URLs Use configuration tools to make modifications and enhancements API Keys Registration and on-board developer portal tools to create keys and change secrets App Developers •Communicate downtime •Block abusing developer •Email developers Developer Portal Updates after changing or adding more functionality to APIs Versioning Set versions; Publish new capability •Where do developers hang out? ‒ Forums ‒ Social Networking sites •Conduct hackathons & App Development competitions •Popular API directories ‒ programmableweb.com ‒ DeveloperWorks
30. 30 30 © 2013 IBM Corporation Summary •Key Concepts – Use REST; consider OAuth, Basic Auth, •Types of API exposure and considerations •Design considerations for REST Based API •Mobility API design considerations •API Security – OAuth, Basic Auth, API Keys •Managing and advertising API
31. 31 31 © 2013 IBM Corporation Expanding to APIs – IBM Services has the Expertise to Ensure Your Success 3 1 • What should my API Strategy be? • How are APIs being used in my industry? • What is needed to expose and manage APIs? • What security do I need? • Who are my target developers? • How do I delivery and measure business value? • How do I get IBM API Management setup quickly? • Help me design my APIs? • How do I expose my backends as APIs? • Help me secure and scale my APIs? • How do I deliver reports to my management? • How do I integrate with existing infrastructure? API Centric Architecture Assessment Roadmap IBM Software Services for API Management For more information contact us at ibmapi@us.ibm.com
32. 32 32 © 2013 IBM Corporation • Emerging technology resources including proven, prescribed, and repeatable assets & offerings to accelerate Mobile, Cloud, and Smarter Process adoption. • Access to worldwide skills, capabilities, and education that only IBM Software Services for WebSphere can bring to your project. • Practitioners’ insight on project trends, best practices and emerging technologies through personal videos, blogs, articles & more. • Discover defined and proven offerings to get your project started quickly. ibm.com/websphere/serviceszone/ ibm.com/websphere/serviceszone/ Visit us in the Solution Center: • Services, Support and Education Zone • Smarter Process Zone IBM Software Services Zone for WebSphere
33. 33 33 © 2013 IBM Corporation We love your Feedback! Don’t forget to submit your Impact session and speaker feedback! •Your feedback is very important to us – we use it to improve next year’s conference •Go to the Impact 2013 SmartSite (http://impactsmartsite/com): ‒ Use the session ID number to locate the session ‒ Click the “Take Survey” link ‒ Submit your feedback
34. 34 34 © 2013 IBM Corporation 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. • If the text contains performance statistics or references to benchmarks, insert the following language; otherwise delete: 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. • If the text includes any customer examples, please confirm we have prior written approval from such customer and insert the following language; otherwise delete: All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics may vary by customer. • Please review text for proper trademark attribution of IBM products. At first use, each product name must be the full name and include appropriate trademark symbols (e.g., IBM Lotus® Sametime® Unyte™). Subsequent references can drop “IBM” but should include the proper branding (e.g., Lotus Sametime Gateway, or WebSphere Application Server). Please refer to http://www.ibm.com/legal/copytrade.shtml for guidance on which trademarks require the ® or ™ symbol. Do not use abbreviations for IBM product names in your presentation. All product names must be used as adjectives rather than nouns. Please list all of the trademarks that you use in your presentation as follows; delete any not included in your presentation. IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, Quickr, Sametime, WebSphere, UC2, PartnerWorld and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both. Unyte is a trademark of WebDialogs, Inc., in the United States, other countries, or both. • If you reference Adobe® in the text, please mark the first use and include the following; otherwise delete: Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. • If you reference Java™ in the text, please mark the first use and include the following; otherwise delete: Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. • If you reference Microsoft® and/or Windows® in the text, please mark the first use and include the following, as applicable; otherwise delete: Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both. • If you reference Intel® and/or any of the following Intel products in the text, please mark the first use and include those that you use as follows; otherwise delete: Intel, Intel Centrino, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. • If you reference UNIX® in the text, please mark the first use and include the following; otherwise delete: UNIX is a registered trademark of The Open Group in the United States and other countries. • If you reference Linux® in your presentation, please mark the first use and include the following; otherwise delete: Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. • If the text/graphics include screenshots, no actual IBM employee names may be used (even your own), if your screenshots include fictitious company names (e.g., Renovations, Zeta Bank, Acme) please update and insert the following; otherwise delete: All references to [insert fictitious company name] refer to a fictitious company and are used for illustration purposes only.
35. 35 35 © 2013 IBM Corporation Backup Slides 35
36. 36 36 © 2013 IBM Corporation