API Workshop Amsterdam presented by API Architect Ronnie Mitra

Please download to get full document.

View again

of 355
All materials on our website are shared by users. If you have any questions about copyright issues, please report us to resolve them. We are always happy to assist you.
 3
 
  This workshop with Ronnie Mitra, Layer 7's Principal API Architect, will examine the key foundational elements necessary for a solid API implementation strategy. Building great APIs is about more than just design; it requires detailed, thoughtful execution. Your API strategy needs to meet the business requirements of your organisation but it must also be flexible enough to meet your developer community’s diverse needs.
Related documents
Share
Transcript
  • 1. Building an API Strategy:Introduction and the Business of APIsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  • 2. API Managementvirtual cloudon-premise
  • 3. API AcademyMike Amundsen Ronnie Mitra
  • 4. www.apiacademy.co
  • 5. Business DriversAPI Styles-- Break --The Developer ExperienceAPI ArchitectureSecuring APIs-- Break --Principles of URI DesignAgenda
  • 6. What areWeb APIs?
  • 7. Connecting things
  • 8. Connecting computer programs
  • 9. APIAll programmers are API designersConnections between modulesLanguage DependantAPIs are constrained by the syntax of thelanguage
  • 10. … over the web
  • 11. Web APIsLanguage IndependentAPIs are constrained by the syntax of the webMost API Design principles can be appliedSome design principles are unique to Web APIs
  • 12. Web ofDocumentsWeb ofAppsWeb ofServicesWeb ofThings
  • 13. The web is ubiquitousAnd universally accessible
  • 14. Publishers retain control
  • 15. Private/Partner or Closed APIs
  • 16. Acme Corp.APIAcme Corp.App
  • 17. Public or Open APIs
  • 18. Acme Corp.APIThird PartyApp
  • 19. Priority:Lower CostPriority:Increased Adoption
  • 20. why build an API?
  • 21. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  • 22. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  • 23. Revenue Source
  • 24. Revenue Sourcehttp://www.flickr.com/photos/inside-south-africa/485356704£0.10 per API Call
  • 25. Revenue Source1000 calls/month5000 calls/month
  • 26. Revenue Source500 calls/month1000 calls/month5000 calls/month
  • 27. Revenue SourceIs your content worth paying for?
  • 28. RevenueSourceInternal Revenue (chargeback)Cost Reduction
  • 29. Revenue SourceStrategy Implications:• Maximize uptime andreliability• Target high revenue consumers• Competitive differentiatorsare a must
  • 30. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  • 31. Consumer Reach
  • 32. Consumer Reach
  • 33. Platforms are not forever!
  • 34. Consumer ReachStrategy Implications:• UX driven interfaces• Specialization may berequired• Difficult to updateapplications
  • 35. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  • 36. MarketingAffiliate ProgramsSometimes you pay the developer.
  • 37. MarketingDraw new visitors in.
  • 38. Marketing
  • 39. MarketingStay above the noise:New channelsInformation-centric marketing
  • 40. MarketingStrategy Implications:• Terms and Services are veryimportant• Identify and reward topperformers• Limit calls and restrictaccess when needed
  • 41. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  • 42. InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectInnovation from within
  • 43. InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectInnovation outside your borders
  • 44. InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectWhen does innovation happen?
  • 45. InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectStrategy Implications:• Design interface for generaluse• Identify success stories• Eliminate misuse
  • 46. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  • 47. IntegrationBusiness driven integrationRegulatory driven integration
  • 48. IntegrationStrategy Implications:• Reduce cost• Reduce cost• Reduce cost
  • 49. Observational Learning:Five Famous Stories of Public APIs
  • 50. 2000 – ebay
  • 51. Started with a paid developer program in 2000Made it free in 2005
  • 52. Consumer ReachMarketing
  • 53. Large developer eco-systemLarge app eco-system
  • 54. 25% of eBay listings come from their API!
  • 55. salesforce2000 – salesforce
  • 56. IntegrationRevenue Source
  • 57. API as a cloud enabler
  • 58. 2004 – Flickr
  • 59. web 2.0 generationthe social evolution
  • 60. Consumer ReachMarketing
  • 61. The rise of self-serviceAnnounced 6 billion photos in August 2011
  • 62. 2006 – Amazon Web Services
  • 63. Started as an online book shop…Became a department store…now?
  • 64. Jeff BezosConnect everythinghttp://www.flickr.com/photos/zippy/2430495092
  • 65. 2004:Hey, why don’t we sell this?
  • 66. Revenue Source
  • 67. Estimated revenue:$1.5B in 2012http://wikibon.org/wiki/v/Cloud_Computing_2013%3A_The_Amazon_Gorilla_Invades_the_Enterprise
  • 68. Twilio or stripe2007 - Twillio
  • 69. Revenue Source
  • 70. The API is the business
  • 71. 100,000 developer milestone in 2012
  • 72. Web API Modern Timeline2000Salesforce APIebay API2002Amazon API2004Flickr API2006Twitter APIFacebook APIGoogle (Maps)API2012Programmableweb.com has7144registeredAPIsSources: apievangelist.comprogrammableweb.cominternetarchive.comSteve Yegge Rantoreilly.com2005ebay makesAPIs free2004First Web 2.0Conference2010Salesforce addsHTTP API2008Programmableweb.com has1000registeredAPIs2005Programmableweb.comlaunched54 APIsregistered.
  • 73. Original APIs are still successfulNew business models have emergedKnow your drivers – design accordinglySummary
  • 74. Building an API Strategy:Introduction and the Business of APIsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  • 75. Building an API Strategy:URI Style Design TipsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  • 76. URI StyleGETPUTPOSTDELETE+ URI
  • 77. URI StyleGET /students/1232
  • 78. URI Style• familiar to web developers• designed for HTTP• URIs are intuitiveAdvantages
  • 79. URI Style• limited to HTTP methods• URI design is not standard• can be ‘chatty’Trade-offs
  • 80. What is ‘good’ API Design?• Easy to learn• Easy to use, even w/o documentation• Hard to misuse• Easy to read and maintain code that uses it• Sufficiently powerful to satisfy requirements• Easy to extend• Appropriate to audienceJoshua Bloch, Principal Software Engineer, Google.
  • 81. Principles of URI Style API Design• URIs should be intuitive and ‘hackable’• The interface should adhere to standards(RFC 2616 and RFC 3986)• The design should be extendable
  • 82. Naming URIs• Names matter!• Establish reserved words and keywords• Names should be meaningful (to theapplication developer)
  • 83. Naming URIs – ExamplesBad:• /Core_Items_DSTSM_1Good:• /charges
  • 84. Defining Resources• Translate interactions into nouns• Build a resource model• Avoid RPC/Tunnel style names• Not everything fits well into theCRUD + Object space
  • 85. Map InteractionsInteraction:“retrieve all my user’s messages”Object:Message
  • 86. Resource ModelMessageTitleAuthorBodyRecipientnnn1n1nn
  • 87. Avoid RPC NamesInteraction:“Retrieve newest messages”RPC-style Name:getNewMessages
  • 88. Not Always EasyInteraction:“Perform a spell-check on thismessage”Object:Message?What method is ‘spell-check’?
  • 89. Not Always EasyInteraction:“Perform a spell-check on thismessage”Object:SpellChecker
  • 90. Types of ResourcesLots of nounsA few operators or controllers
  • 91. Relationshipsmyapi/messagesmyapi/messages/14myapi/messages/titlemyapi.com/ronnie/messages/title
  • 92. RelationshipsDon’t expose relationships unless theyare useful to the developerEach path segment should beactionable
  • 93. HTTP Methods• GET• PUT• POST• DELETE• HEAD• OPTION• TRACE• CONNECT
  • 94. GET• Retrieve a representation• ‘safe’ method according to RFC• no user-requested side effects• won’t impact data• ‘Conditional GET’ is supported withcaching• Don’t abuse for non-read operations
  • 95. PUT• Write a representation• Store the entity (full replacement)• Idempotent• Example:PUT /myapi/messages/14{Message}
  • 96. IdempotenceNo side-effects on identical callsPUT /myapi/messages/14Result: Message ReplacedPUT /myapi/messages/14Result: Message Replaced
  • 97. Full ReplacementPUT /myapi/messages/14{ “title”: “Welcome”}{“id”:”14”“title”:”Wlecome”“author”:”Ronnie”“body”: “Hi Glen, welcome to the team!”}On the Server:{“title”:”Wlecome”}
  • 98. Why not use PUT for partial update?• Breaks HTTP specification• No defined semantic – can produceunexpected results from a devperspective
  • 99. PATCH (Partial Update)• RFC 5789 (HTTP Patch)• Partially update an identifiedresource with the supplied entity• Example:PATCH /myapi/message/14{Partial Message}
  • 100. Patch Media Type• RFC 6902 – JSON Patch• Content-Type: application/json-patch+jsonPATCH /myapi/message/14 HTTP/1.1[{ "op": “replace", "path": "/subject", "value": “new" },{ "op": “add", "path": "/tags", "value": “urgent" }]
  • 101. Challenges with PATCH• Not part of HTTP 1.1 spec• Not widely adopted inimplementations• May not be familiar to developeraudience
  • 102. How do I implement PATCH inan environment that doesn’tsupport it?
  • 103. PATCH WorkaroundsTurn the target data into a URI object:HTTP PUT /myapi/messages/14/title
  • 104. PATCH WorkaroundsTunnel the patch with a custom header:X-HTTP-Method-Override: PATCH
  • 105. PATCH WorkaroundsUse a unique URL:HTTP POST /myapi/patches/messages/14HTTP POST /myapi/messages/14/patchesHTTP POST /myapi/messages/14;patch
  • 106. PATCH WorkaroundsUse PUT and break the specification
  • 107. POST• Write/Process an entity• Accept entity as sub-ordinateresource• Not Idempotent• No identifier specified (factorypattern):POST /myapi/messages
  • 108. Non-IdempotentPOST /myapi/messagesResult: Message #14 CreatedPOST /myapi/messagesResult: Message #15 Created
  • 109. DELETE• Delete identified resource• Example:DELETE /myapi/messages/14• Idempotent
  • 110. Method Tunneling• Older platforms may not support allverbs• Need to resort to embedding theverb in a header or parameter• Example:GET myapi/shops?method=POST• Avoid doing this
  • 111. RepresentationsExpose object properties that arerelevant to the developerEmbed child objects and properties,but need to decide on granularityDesign structures that are extensible –be careful when implementingschema
  • 112. Representations - Granularity{“id” : “14”“title” : “Welcome”“body” : “Hello!”“author” : “38820”}
  • 113. Representations - Granularity{“id” : “14”“title” : “Welcome”“body” : “Hello!”“author” : [ “id” : “38820”,“firstName” : “Ronnie” ]}
  • 114. Representations – GranularityConsiderationsChattiness vs. LatencyFrequency of changeInteraction (what data is needed?)
  • 115. Retrieve a Collection of Data• Example: “Retrieve all storelocations”• GET /shops
  • 116. Retrieve a Filtered Collection of Data• Filter by requesting children• GET /shops/london• GET /shops/amsterdam• Limited to objects and sub-objects• Difficult to retrieve unions/joins of data
  • 117. Retrieve a Filtered Collection of Data• Example: “Retrieve all store locations inLondon”• Use query parameter from URI spec• GET /shops?location=London• GET /shops?location=London,Amsterdam• GET /shops?location=London&sort=distance
  • 118. Complex Queries“retrieve all shops within a radius of 10 kmfrom a specific location that are openwithin specified hours and sell specificphones, devices and account plans”GET/shops?radius=10&location=8882,28832&open_time=38882034&close_time=23882343&phones=iphone,blackberry,samsung&plans=monthly_3GB,monthly_4GB,pay_go_2GB
  • 119. Complex QueriesURI space may be limitedLong queries can become difficult tomanageUse POST on an operator resource:POST /shopsquery{“radius” : “10”, “location” : “388203,838200”,“phones” : [“blackberry”, “iphone”]}
  • 120. Returning Collections• array of results• all properties and child elements?• collection responses can be BIG!
  • 121. Pagination• Just like websites – break data upinto manageable ‘pages’
  • 122. Pagination• data page mechanism/api/resource?page=3• fixed page sizePage 1 Page 2 Page 3 Page 4 Page 5 Page 6• easy to navigate
  • 123. Pagination• offset + count mechanism/api/resource?offset=10&count=20• client app dictates page size10 30• client calculates offset and count forpages
  • 124. Pagination• use links to navigate{“href”:“/api/resource?offset=11&count=20”,“rel”:“next”}• client doesn’t have to calculatelocation• easier to navigate through pages
  • 125. Pagination• use defaults to reduce ‘friction’• reduces learning curve for newdevelopers/api/resource?offset=10&count=20/api/resource/api/resource?offset=10&count=10
  • 126. Field Projection•‘property selection’, ‘zooming’• Collections can be too big for someclient• Allow client to select properties inrepresentations
  • 127. Field Projection - ExampleGET /myapi/messages?fields=title,body{[{“id”: “1”, “title” : “hi!”, “body” :“hello”}…]}
  • 128. Linking• Use links as identifiers{[{“id”: “/myapi/messages/13”},{“id”: “/myapi/messages/14”}]}
  • 129. LinkingAdvantages:• Developer doesn’t need to constructURI• URIs can change!Trade-offs:• Query parameters increasecomplexity
  • 130. Implementing LinkingLots of Standards:• HAL• SIREN• Collection + JSON• ATOM• XML LINKING• HTML
  • 131. Implementing LinkingLots of APIs just do this:{“link_name” : “link”}
  • 132. Implementing Versioning• myapi/v1/path• Try to extend instead of version• Don’t break what is already there• Clients should ignore what theydon’t understand• Introduce breaking changes if youwant to drive developers away.
  • 133. Content Types• XML• JSON• HTML
  • 134. XML• Not the same as SOAP / Tunnel Style• Widely used (AJAX, mobile, server)• W3C Standard, RFC 3023
  • 135. JSON• Usage rising• Popular amongst next-gen developers• JavaScript everywhere• RFC 4627
  • 136. XML vs. JSON?• Not very different• ‘<‘ vs. ‘{‘• Similar performance overhead• Most clients support both (XMLmore widely supported)• What do your developer’s prefer?
  • 137. HTML• Hypermedia content type• Web Form: application/x-www-form-urlencoded• Useful for simple name/value pairinput• Easy for developers to implement
  • 138. Selecting a Representation• Content Negotiation• HTTP Accept Header• URI based• /myapi/messages.xml
  • 139. Status Codes• 1xx: Informational• 2xx: Success• 3xx: Redirection• 4xx: Client Error• 5xx: Server Error
  • 140. Status Codes• You MUST use the correct category• The second part of the code (xx) islargely informational, but stillimportant• Reason phrases can be customized
  • 141. Status CodesClient libraries should handle statuscodes and act in an expected manner
  • 142. Error Handling• You might include an applicationlevel error code• Definitely Include a human readableerror message
  • 143. A Few Interactions
  • 144. Asynchronous RequestClient Resource202 AcceptedFire and Forget
  • 145. Asynchronous RequestClient Resource202 Accepted<link href=“…” rel=“status”/>StatusResource200 OK<status>complete</status><link href=“…” rel=“result”/>
  • 146. Server CallbackClient ResourceRegister200 OK200 OKNotify
  • 147. Server Event (Long Poll)Client ResourceBlock and Wait200 OKHTTP Abuse
  • 148. Optimizations
  • 149. Optimizations• Mobile and device platforms haveunique bandwidth constraints• Transport Level (HTTP)• API Design
  • 150. HTTP Optimizations• Compression• Negotiation (Accept-Encoding)• Example:• Is JSON more efficient than XML?Accept-Encoding: compress, gzip
  • 151. HTTP Optimizations• Pipelining• Multiple requests without waitingfor response• Supported in HTTP 1.1 (persistentconnections)• Idempotent actions only
  • 152. API Design OptimizationsReduce data size (pagination, fieldprojection)Reduce number of calls:• Composition• RPC batch• Caching
  • 153. CompositionURI style APIs can be chattyCombine interactions and expose onthe serverExample:/myapi/composer
  • 154. BatchingURI style APIs can be chattyCombine and invoke calls on the clientCan be complicated for the developer
  • 155. CachingMany forms of cachingHTTP Caching avoids use of networkWidely supported
  • 156. Adaptive Responses• Provide responses that are the bestfit for the calling application•Examples:• Reduced granularity• Different defaults• UI Driven
  • 157. URI Design Summary• Some standards, but lots of choices• Design with developer in mind• Consistency and structure areimportant
  • 158. Building an API Strategy:URI Style Design TipsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  • 159. Building an API Strategy:The Developer ExperienceRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  • 160. designing APIs can be difficult
  • 161. http://www.flickr.com/photos/nirufe/3469696707?
  • 162. UsabilityReliabilitySimplicitySecurityEtc…Software Qualities
  • 163. Focus on the developer experience(dx)
  • 164. Interaction DesignBill Moggridge
  • 165. UsabilityHuman-Computer-InteractionUser Experience DesignGoal Oriented Design
  • 166. http://www.flickr.com/photos/58754750@N08/5541472392/
  • 167. A user-centric view of design.
  • 168. Well designed products are easierto use.
  • 169. Good design matters for Web APIstoo.
  • 170. Priority:Lower CostPriority:Increased Adoption
  • 171. PortalAPI
  • 172. PortalAPIDeveloperEnd UserAdministrator
  • 173. PortalAPI
  • 174. This is obvious right?
  • 175. Why is this difficult to do in practice?
  • 176. Reason #1We project our own perspective.
  • 177. Reason #2We project our own biases.
  • 178. Never use SOAP?Why?
  • 179. Consider keyboards…
  • 180. http://www.flickr.com/photos/yvettemn/139890573/
  • 181. http://www.flickr.com/photos/jonathanpberger/7126054997/
  • 182. http://www.flickr.com/photos/novemberborn/286773981/
  • 183. OR
  • 184. It doesn’t matter that you don’t likeSOAP.
  • 185. What matters is what your developerbase thinks!(and what your objective is)
  • 186. Reason #3We make bad assumptions.
  • 187. API publishers are also developers.
  • 188. “I built a mobile app once.”
  • 189. Reason #4We lack the time, money orincentive for good design
  • 190. “Best practices”, patterns andstandards become shortcuts
  • 191. Am I RESTfull enough?
  • 192. So, how can we do better?
  • 193. Developer-centric design requireseffort and diligence.
  • 194. Design with the developer in mind.
  • 195. Ask them.
  • 196. • Interviews• Surveys• Listen (blogs, presentations,tweets)
  • 197. +
  • 198. • Observe• Prototype• Analyze Historical Data
  • 199. Consider all aspects of the DX:RegistrationSecurityTroubleshootingLearningInterface Style
  • 200. A Good DX = A Good System
  • 2
  • Related Search
    We Need Your Support
    Thank you for visiting our website and your interest in our free products and services. We are nonprofit website to share and download documents. To the running of this website, we need your help to support us.

    Thanks to everyone for your continued support.

    No, Thanks