Your SlideShare is downloading. ×
Recommended Practices for Designing a Web API
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.


Introducing the official SlideShare app

Stunning, full-screen experience for iPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Recommended Practices for Designing a Web API


Published on

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. …

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.

Published in: Technology, Business

  • 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. © 2013 IBM CorporationRecommended Practices for Designing a Web APIAlan Moore,Senior Technical Staff Member, AIM, SWGDinesh Shetty,Senior Certified IT Specialist, ISSW2372
  • 2. 22 © 2013 IBM CorporationPlease NoteIBM’s statements regarding its plans, directions, and intent are subject to changeor withdrawal without notice at IBM’s sole discretion.Information regarding potential future products is intended to outline our generalproduct direction and it should not be relied on in making a purchasing decision.The information mentioned regarding potential future products is not acommitment, promise, or legal obligation to deliver any material, code orfunctionality. Information about potential future products may not be incorporatedinto any contract. The development, release, and timing of any future features orfunctionality described for our products remains at our sole discretion.Performance is based on measurements and projections using standard IBMbenchmarks in a controlled environment. The actual throughput or performancethat any user will experience will vary depending upon many factors, includingconsiderations 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 resultssimilar to those stated here.
  • 3. 33 © 2013 IBM CorporationAgenda•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. 44 © 2013 IBM CorporationKey Concepts – Terminologies, technologies & benefits•Web API‒ A defined set of HTTP requestand response message‒ typically expressedin JSON or XML•Mashup‒ A web application that usesWeb APIs to combine data,presentation‒ from two or more sources tocreate new services•Apps‒ An application accessed overthe Internet or an intranet.‒ Coded in a browser-supportedprogramming language (suchas JavaScript and markuplanguage 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 yourenterprise assets‒ Rapidly develop web, mobileand tablet applications fromyour organizations technicalassets
  • 5. 55 © 2013 IBM CorporationKey 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. 66 © 2013 IBM Corporation70% of Web APIs are REST; REST is simpleSource: is an architectural style; not a standard
  • 7. 77 © 2013 IBM CorporationAPI Exposures – Public? Private?Protected?7
  • 8. 88 © 2013 IBM CorporationA Little More Info on the Types Of API ExposuresPublic, Open-To-All APIsProtected, Open-To-Partner APIsPrivate, Open-To-EmployeeAPIs• APIs are open to any developerwho wants to sign up• Apps are more targetedtowards end consumers• The business driver is toengage customers throughexternal developers• APIs are open to selectbusiness partners• Apps could be targeted at endconsumers or business users• The business driver is usuallydifferent, based on the data andtype of business of theenterprise• APIs are exposed only toexisting developers within theenterprise• Apps are usually targeted atemployees of the enterprise• The business driver is morearound productivity ofemployees
  • 9. 99 © 2013 IBM CorporationQuestions and Considerations•No “One rule fits all” recommendation – more of a business decision foran 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 onlyrequired fields from a response•How much functionality is to be provided in an API?‒ Organizations chose to provide limited, but important capability throughAPIs‒ E.g. Comprehensive banking capabilities Vs. basic quick-use tasks•Both versions – Public and Private?‒ Management overheads
  • 10. 1010 © 2013 IBM Corporation•Designing a REST-based Web API• Typical API developerrequirements•Walkthrough• Sample Application10
  • 11. 1111 © 2013 IBM CorporationTypical 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 andwon’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 avolume 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 differenttimezone) – with forums, bug reporting, community tools, API status visibility etc•Show me my API usage, my users’ usage, my data
  • 12. 1212 © 2013 IBM CorporationUse CachingArchitect your backend for scalingLeverageAsynchronousMessagingUse CompressionBuild on anElasticPlatform
  • 13. 1313 © 2013 IBM CorporationAccounts ContactsOpportunitiesSample 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. 1414 © 2013 IBM CorporationAccount REST API for Sample Application•GET /Accounts‒ SELECT *FROM Accounts•GET /Accounts/{Id}‒ SELECT *FROM AccountsWHERE Id = ?•GET /Accounts/{id}/Contacts‒ SELECT C.*FROM Contacts CWHERE C.AccountId = ?•GET /Accounts/{id}/Opportunities‒ SELECT O.*FROM Opportunities OWHERE O.AccountId = ?
  • 15. 1515 © 2013 IBM CorporationContacts REST API for Sample Application•GET /Contacts‒ SELECT *FROM Contacts•GET /Contacts/{Id}‒ SELECT *FROM ContactsWHERE Id = ?•GET /Contacts/{id}/Accounts‒ SELECT A.*FROM Accounts A, Contacts CWHERE C.Id = ? AND A.Id = C.AccountId•GET /Contacts/{id}/Opportunities‒ SELECT O.*FROM Opportunities OWHERE O.ContactId = ?
  • 16. 1616 © 2013 IBM CorporationOpportunities REST API for Sample Application•GET /Opportunities‒ SELECT *FROM Opportunities•GET /Opportunities/{Id}‒ SELECT *FROM OpportunitiesWHERE Id = ?•GET /Opportunities/{id}/Accounts‒ SELECT A.*FROM Accounts A, Opportunities OWHERE O.Id = ? AND A.Id = O.AccountId•GET /Opportunities/{id}/Contacts‒ SELECT C.*FROM Opportunities O, Contacts CWHERE O.Id = ? AND O.ContactId = C.Id
  • 17. 1717 © 2013 IBM CorporationDelete REST Operations for Sample Application•DELETE /Accounts/{Id}‒ DELETEFROM AccountsWHERE Id = ?•DELETE /Contacts/{Id}‒ DELETEFROM ContactsWHERE Id = ?•DELETE /Opportunities/{Id}‒ DELETEFROM OpportunitiesWHERE Id = ?•Depending on the relationships, some APIs may need to update thedependent objects to ensure referential integrity•E.g. A primary contact for an opportunity or account leaving the company
  • 18. 1818 © 2013 IBM CorporationDesign a mobile-friendly Web API18
  • 19. 1919 © 2013 IBM CorporationKey Mobility API Design considerationsKey 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 timesDesign 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 downif not‒ Aggregation ideally done at the backend
  • 20. 2020 © 2013 IBM CorporationKey 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; lightweightNatural and easy to use from JavaScriptJavaScript 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 JSONXML continues to be leading choice of format for APIs‒ Key: Keep your request and responses simpleThink about pagination, limits when returning large set of resultsE.g. LinkedIn API – uses start and count parameters
  • 21. 2121 © 2013 IBM CorporationImplementing Caching foryour API21
  • 22. 2222 © 2013 IBM CorporationImplement CachingHTTP headers can contain caching directivesHTTP/1.1 200 OKDate: Fri, 30 Oct 1998 13:19:41 GMTServer: Apache/1.3.3 (Unix)Cache-Control: max-age=3600, must-revalidateExpires: Fri, 30 Oct 1998 14:19:41 GMTLast-Modified: Mon, 29 Jun 1998 02:28:12 GMTETag: "3e86-410-3596fbbc"Content-Length: 1040Content-Type: text/htmlCaches improve network efficiency, improves scalability, and improvesuser-perceived performance of your API
  • 23. 2323 © 2013 IBM CorporationSecuring your API23
  • 24. 2424 © 2013 IBM CorporationSecurity mechanisms for Web APIsOAuth•Enables users to allow webapplications to access other webapplications on the user’s behalfBasic Auth•Passes Username and password with therequest•Defined by the HTTP specification•Uses HTTP Header “Authorization”•Uses encoding, no encryptionAPI Keys•Not based on any standard•Service Provider decidesimplementation•Keys act like signatures
  • 25. 2525 © 2013 IBM CorporationSecurity Mechanisms - OAuth“The OAuth 2.0 authorization framework enables a third-party application toobtain limited access to an HTTP service, either on behalf of a resourceowner by orchestrating an approval interaction between the resourceowner and the HTTP service, or by allowing the third-party application toobtain access on its own behalf”FourSquareTwitterSteve, logged on Foursquare, wantsto update his holiday location andalso post the same on his TwitterpageTwitter provides an access token toFoursquare that provides access toSteve’s twitter pageForsquare uses access tokenprovided by twitter to make a poston twitter on Steve’s behalfAccess token (no user id/password) required
  • 26. 2626 © 2013 IBM CorporationSecurity Mechanisms - OAuth
  • 27. 2727 © 2013 IBM CorporationBasic 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 clientsPart of nearly every HTTP request library‒ Simple Server setupUse 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. 2828 © 2013 IBM CorporationAPI 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 proprietaryimplementation•Basics‒ Key is part of URL (how to is described in API documentation)‒ For e.g.•Pros‒ Easy key generation and distribution‒ No username and password required in raw form•Cons‒ Unsigned‒ Must embed them in code‒ Transmitted in plain textBest Practices•Use signed requests over unsigned•One key per application per developer•Require username in headers
  • 29. 2929 © 2013 IBM CorporationManaging and advertizing your APIsWhat needs management? How to manage?API and Resource URLs Use configuration tools to make modificationsand enhancementsAPI Keys Registration and on-board developer portal toolsto create keys and change secretsApp Developers •Communicate downtime•Block abusing developer•Email developersDeveloper Portal Updates after changing or adding morefunctionality to APIsVersioning Set versions; Publish new capability•Where do developers hang out?‒ Forums‒ Social Networking sites•Conduct hackathons & App Development competitions•Popular API directories‒‒ DeveloperWorks
  • 30. 3030 © 2013 IBM CorporationSummary•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. 3131 © 2013 IBM CorporationExpanding to APIs – IBM Serviceshas the Expertise to Ensure Your Success31• 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 CentricArchitectureAssessmentRoadmapIBM SoftwareServices forAPIManagementFor more information contact us at
  • 32. 3232 © 2013 IBM Corporation• Emerging technology resources includingproven, prescribed, and repeatable assets &offerings to accelerate Mobile, Cloud, andSmarter Process adoption.• Access to worldwide skills, capabilities, andeducation that only IBM Software Servicesfor WebSphere can bring to your project.• Practitioners’ insight on project trends,best practices and emerging technologiesthrough personal videos, blogs, articles &more.• Discover defined and proven offerings toget your project started us in the Solution Center:• Services, Support and Education Zone• Smarter Process ZoneIBM Software Services Zone for WebSphere
  • 33. 3333 © 2013 IBM CorporationWe 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’sconference•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. 3434 © 2013 IBM CorporationLegal 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 containedin 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 aresubject 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. Nothingcontained 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 andconditions 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/orcapabilities 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 tofuture 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 byyou 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 willexperience will vary depending upon many factors, including considerations such as the amount of multiprogramming in the users job stream, the I/O configuration, the storageconfiguration, 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 costsand 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., IBMLotus® 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 for guidance on which trademarks require the ® or ™ symbol. Do not use abbreviations for IBM product names in yourpresentation. 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 inyour presentation. IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, Quickr, Sametime, WebSphere, UC2, PartnerWorld and Lotusphere are trademarks of InternationalBusiness 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 andother 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 ofothers.• 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, ZetaBank, 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 illustrationpurposes only.
  • 35. 3535 © 2013 IBM CorporationBackup Slides35
  • 36. 3636 © 2013 IBM Corporation