Building an API Strategy:Introduction and the Business of APIsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Acad...
API Managementvirtual cloudon-premise
API AcademyMike Amundsen Ronnie Mitra
www.apiacademy.co
Business DriversAPI Styles-- Break --The Developer ExperienceAPI ArchitectureSecuring APIs-- Break --Principles of URI Des...
What areWeb APIs?
Connecting things
Connecting computer programs
APIAll programmers are API designersConnections between modulesLanguage DependantAPIs are constrained by the syntax of...
… over the web
Web APIsLanguage IndependentAPIs are constrained by the syntax of the webMost API Design principles can be appliedSome...
Web ofDocumentsWeb ofAppsWeb ofServicesWeb ofThings
The web is ubiquitousAnd universally accessible
Publishers retain control
Private/Partner or Closed APIs
Acme Corp.APIAcme Corp.App
Public or Open APIs
Acme Corp.APIThird PartyApp
Priority:Lower CostPriority:Increased Adoption
why build an API?
InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
Revenue Source
Revenue Sourcehttp://www.flickr.com/photos/inside-south-africa/485356704£0.10 per API Call
Revenue Source1000 calls/month5000 calls/month
Revenue Source500 calls/month1000 calls/month5000 calls/month
Revenue SourceIs your content worth paying for?
RevenueSourceInternal Revenue (chargeback)Cost Reduction
Revenue SourceStrategy Implications:• Maximize uptime andreliability• Target high revenue consumers• Competitive different...
InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
Consumer Reach
Consumer Reach
Platforms are not forever!
Consumer ReachStrategy Implications:• UX driven interfaces• Specialization may berequired• Difficult to updateapplications
InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
MarketingAffiliate ProgramsSometimes you pay the developer.
MarketingDraw new visitors in.
Marketing
MarketingStay above the noise:New channelsInformation-centric marketing
MarketingStrategy Implications:• Terms and Services are veryimportant• Identify and reward topperformers• Limit calls and ...
InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectInnovation from within
InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectInnovation outside your borders
InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectWhen does innovation happen?
InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectStrategy Implications:• Design interface for g...
InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
IntegrationBusiness driven integrationRegulatory driven integration
IntegrationStrategy Implications:• Reduce cost• Reduce cost• Reduce cost
Observational Learning:Five Famous Stories of Public APIs
2000 – ebay
Started with a paid developer program in 2000Made it free in 2005
Consumer ReachMarketing
Large developer eco-systemLarge app eco-system
25% of eBay listings come from their API!
salesforce2000 – salesforce
IntegrationRevenue Source
API as a cloud enabler
2004 – Flickr
web 2.0 generationthe social evolution
Consumer ReachMarketing
The rise of self-serviceAnnounced 6 billion photos in August 2011
2006 – Amazon Web Services
Started as an online book shop…Became a department store…now?
Jeff BezosConnect everythinghttp://www.flickr.com/photos/zippy/2430495092
2004:Hey, why don’t we sell this?
Revenue Source
Estimated revenue:$1.5B in 2012http://wikibon.org/wiki/v/Cloud_Computing_2013%3A_The_Amazon_Gorilla_Invades_the_Enterprise
Twilio or stripe2007 - Twillio
Revenue Source
The API is the business
100,000 developer milestone in 2012
Web API Modern Timeline2000Salesforce APIebay API2002Amazon API2004Flickr API2006Twitter APIFacebook APIGoogle (Maps)API20...
Original APIs are still successfulNew business models have emergedKnow your drivers – design accordinglySummary
Building an API Strategy:Introduction and the Business of APIsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Acad...
Building an API Strategy:URI Style Design TipsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
URI StyleGETPUTPOSTDELETE+ URI
URI StyleGET /students/1232
URI Style• familiar to web developers• designed for HTTP• URIs are intuitiveAdvantages
URI Style• limited to HTTP methods• URI design is not standard• can be ‘chatty’Trade-offs
What is ‘good’ API Design?• Easy to learn• Easy to use, even w/o documentation• Hard to misuse• Easy to read and maintain ...
Principles of URI Style API Design• URIs should be intuitive and ‘hackable’• The interface should adhere to standards(RFC ...
Naming URIs• Names matter!• Establish reserved words and keywords• Names should be meaningful (to theapplication developer)
Naming URIs – ExamplesBad:• /Core_Items_DSTSM_1Good:• /charges
Defining Resources• Translate interactions into nouns• Build a resource model• Avoid RPC/Tunnel style names• Not everythin...
Map InteractionsInteraction:“retrieve all my user’s messages”Object:Message
Resource ModelMessageTitleAuthorBodyRecipientnnn1n1nn
Avoid RPC NamesInteraction:“Retrieve newest messages”RPC-style Name:getNewMessages
Not Always EasyInteraction:“Perform a spell-check on thismessage”Object:Message?What method is ‘spell-check’?
Not Always EasyInteraction:“Perform a spell-check on thismessage”Object:SpellChecker
Types of ResourcesLots of nounsA few operators or controllers
Relationshipsmyapi/messagesmyapi/messages/14myapi/messages/titlemyapi.com/ronnie/messages/title
RelationshipsDon’t expose relationships unless theyare useful to the developerEach path segment should beactionable
HTTP Methods• GET• PUT• POST• DELETE• HEAD• OPTION• TRACE• CONNECT
GET• Retrieve a representation• ‘safe’ method according to RFC• no user-requested side effects• won’t impact data• ‘Condit...
PUT• Write a representation• Store the entity (full replacement)• Idempotent• Example:PUT /myapi/messages/14{Message}
IdempotenceNo side-effects on identical callsPUT /myapi/messages/14Result: Message ReplacedPUT /myapi/messages/14Result: M...
Full ReplacementPUT /myapi/messages/14{ “title”: “Welcome”}{“id”:”14”“title”:”Wlecome”“author”:”Ronnie”“body”: “Hi Glen, w...
Why not use PUT for partial update?• Breaks HTTP specification• No defined semantic – can produceunexpected results from a...
PATCH (Partial Update)• RFC 5789 (HTTP Patch)• Partially update an identifiedresource with the supplied entity• Example:PA...
Patch Media Type• RFC 6902 – JSON Patch• Content-Type: application/json-patch+jsonPATCH /myapi/message/14 HTTP/1.1[{ "op":...
Challenges with PATCH• Not part of HTTP 1.1 spec• Not widely adopted inimplementations• May not be familiar to developerau...
How do I implement PATCH inan environment that doesn’tsupport it?
PATCH WorkaroundsTurn the target data into a URI object:HTTP PUT /myapi/messages/14/title
PATCH WorkaroundsTunnel the patch with a custom header:X-HTTP-Method-Override: PATCH
PATCH WorkaroundsUse a unique URL:HTTP POST /myapi/patches/messages/14HTTP POST /myapi/messages/14/patchesHTTP POST /myapi...
PATCH WorkaroundsUse PUT and break the specification
POST• Write/Process an entity• Accept entity as sub-ordinateresource• Not Idempotent• No identifier specified (factorypatt...
Non-IdempotentPOST /myapi/messagesResult: Message #14 CreatedPOST /myapi/messagesResult: Message #15 Created
DELETE• Delete identified resource• Example:DELETE /myapi/messages/14• Idempotent
Method Tunneling• Older platforms may not support allverbs• Need to resort to embedding theverb in a header or parameter• ...
RepresentationsExpose object properties that arerelevant to the developerEmbed child objects and properties,but need to de...
Representations - Granularity{“id” : “14”“title” : “Welcome”“body” : “Hello!”“author” : “38820”}
Representations - Granularity{“id” : “14”“title” : “Welcome”“body” : “Hello!”“author” : [ “id” : “38820”,“firstName” : “Ro...
Representations – GranularityConsiderationsChattiness vs. LatencyFrequency of changeInteraction (what data is needed?)
Retrieve a Collection of Data• Example: “Retrieve all storelocations”• GET /shops
Retrieve a Filtered Collection of Data• Filter by requesting children• GET /shops/london• GET /shops/amsterdam• Limited to...
Retrieve a Filtered Collection of Data• Example: “Retrieve all store locations inLondon”• Use query parameter from URI spe...
Complex Queries“retrieve all shops within a radius of 10 kmfrom a specific location that are openwithin specified hours an...
Complex QueriesURI space may be limitedLong queries can become difficult tomanageUse POST on an operator resource:POST /sh...
Returning Collections• array of results• all properties and child elements?• collection responses can be BIG!
Pagination• Just like websites – break data upinto manageable ‘pages’
Pagination• data page mechanism/api/resource?page=3• fixed page sizePage 1 Page 2 Page 3 Page 4 Page 5 Page 6• easy to nav...
Pagination• offset + count mechanism/api/resource?offset=10&count=20• client app dictates page size10 30• client calculate...
Pagination• use links to navigate{“href”:“/api/resource?offset=11&count=20”,“rel”:“next”}• client doesn’t have to calculat...
Pagination• use defaults to reduce ‘friction’• reduces learning curve for newdevelopers/api/resource?offset=10&count=20/ap...
Field Projection•‘property selection’, ‘zooming’• Collections can be too big for someclient• Allow client to select proper...
Field Projection - ExampleGET /myapi/messages?fields=title,body{[{“id”: “1”, “title” : “hi!”, “body” :“hello”}…]}
Linking• Use links as identifiers{[{“id”: “/myapi/messages/13”},{“id”: “/myapi/messages/14”}]}
LinkingAdvantages:• Developer doesn’t need to constructURI• URIs can change!Trade-offs:• Query parameters increasecomplexity
Implementing LinkingLots of Standards:• HAL• SIREN• Collection + JSON• ATOM• XML LINKING• HTML
Implementing LinkingLots of APIs just do this:{“link_name” : “link”}
Implementing Versioning• myapi/v1/path• Try to extend instead of version• Don’t break what is already there• Clients shoul...
Content Types• XML• JSON• HTML
XML• Not the same as SOAP / Tunnel Style• Widely used (AJAX, mobile, server)• W3C Standard, RFC 3023
JSON• Usage rising• Popular amongst next-gen developers• JavaScript everywhere• RFC 4627
XML vs. JSON?• Not very different• ‘<‘ vs. ‘{‘• Similar performance overhead• Most clients support both (XMLmore widely su...
HTML• Hypermedia content type• Web Form: application/x-www-form-urlencoded• Useful for simple name/value pairinput• Easy f...
Selecting a Representation• Content Negotiation• HTTP Accept Header• URI based• /myapi/messages.xml
Status Codes• 1xx: Informational• 2xx: Success• 3xx: Redirection• 4xx: Client Error• 5xx: Server Error
Status Codes• You MUST use the correct category• The second part of the code (xx) islargely informational, but stillimport...
Status CodesClient libraries should handle statuscodes and act in an expected manner
Error Handling• You might include an applicationlevel error code• Definitely Include a human readableerror message
A Few Interactions
Asynchronous RequestClient Resource202 AcceptedFire and Forget
Asynchronous RequestClient Resource202 Accepted<link href=“…” rel=“status”/>StatusResource200 OK<status>complete</status><...
Server CallbackClient ResourceRegister200 OK200 OKNotify
Server Event (Long Poll)Client ResourceBlock and Wait200 OKHTTP Abuse
Optimizations
Optimizations• Mobile and device platforms haveunique bandwidth constraints• Transport Level (HTTP)• API Design
HTTP Optimizations• Compression• Negotiation (Accept-Encoding)• Example:• Is JSON more efficient than XML?Accept-Encoding:...
HTTP Optimizations• Pipelining• Multiple requests without waitingfor response• Supported in HTTP 1.1 (persistentconnection...
API Design OptimizationsReduce data size (pagination, fieldprojection)Reduce number of calls:• Composition• RPC batch• Cac...
CompositionURI style APIs can be chattyCombine interactions and expose onthe serverExample:/myapi/composer
BatchingURI style APIs can be chattyCombine and invoke calls on the clientCan be complicated for the developer
CachingMany forms of cachingHTTP Caching avoids use of networkWidely supported
Adaptive Responses• Provide responses that are the bestfit for the calling application•Examples:• Reduced granularity• Dif...
URI Design Summary• Some standards, but lots of choices• Design with developer in mind• Consistency and structure areimpor...
Building an API Strategy:URI Style Design TipsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
Building an API Strategy:The Developer ExperienceRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
designing APIs can be difficult
http://www.flickr.com/photos/nirufe/3469696707?
UsabilityReliabilitySimplicitySecurityEtc…Software Qualities
Focus on the developer experience(dx)
Interaction DesignBill Moggridge
UsabilityHuman-Computer-InteractionUser Experience DesignGoal Oriented Design
http://www.flickr.com/photos/58754750@N08/5541472392/
A user-centric view of design.
Well designed products are easierto use.
Good design matters for Web APIstoo.
Priority:Lower CostPriority:Increased Adoption
PortalAPI
PortalAPIDeveloperEnd UserAdministrator
PortalAPI
This is obvious right?
Why is this difficult to do in practice?
Reason #1We project our own perspective.
Reason #2We project our own biases.
Never use SOAP?Why?
Consider keyboards…
http://www.flickr.com/photos/yvettemn/139890573/
http://www.flickr.com/photos/jonathanpberger/7126054997/
http://www.flickr.com/photos/novemberborn/286773981/
OR
It doesn’t matter that you don’t likeSOAP.
What matters is what your developerbase thinks!(and what your objective is)
Reason #3We make bad assumptions.
API publishers are also developers.
“I built a mobile app once.”
Reason #4We lack the time, money orincentive for good design
“Best practices”, patterns andstandards become shortcuts
Am I RESTfull enough?
So, how can we do better?
Developer-centric design requireseffort and diligence.
Design with the developer in mind.
Ask them.
• Interviews• Surveys• Listen (blogs, presentations,tweets)
+
• Observe• Prototype• Analyze Historical Data
Consider all aspects of the DX:RegistrationSecurityTroubleshootingLearningInterface Style
A Good DX = A Good System
Tunnel StyleURI StyleHypermedia StyleEvent Driven Style
RegistrationLazy RegistrationSocial IntegrationPersonalization
Development Activity Cycle1. Learn2. Code3. Implement4. Test5. Fix
PortalAPILearnCodeTest
APILearnTest
API explorers and “livedocumentation” can shorten thegap between visibility andfeedback.
LearningWADLs and WSDLs are niceBut provide real documentation for humans!Hypermedia =/= zero documentation
TLSOAuth 2Open ID Connect
SecuritySecurity can hurt UsabilityBut… security can also improve theoverall experience!We need to think about the system ...
Complexity• Sometimes complexity is necessary –that is ok• Enough features to meetrequirements• Don’t hurt the DX – use st...
Structure and ConsistencyDefine a consistent Message Structure{ “Response” : {“Errors” : {}}}
Structure and ConsistencyDefine consistent standards for:• Naming• Collection structure• Content negotiation• Links
Structure and ConsistencyEnforcing standards requiresorganizational disciplineEspecially difficult in largeorganizations!
ModularityPartition APIs into modules orproductsFrom a DEVELOPER perspective!
“Frictionless” integrationHigh rates of adoptionLow cost integrationWe want:
Behaviour DesignBJ Fogg
Visitor Invested Developer
JoyVisitorInvested DeveloperJoyJoy
A Sample DX Based Design Process
1. Define the problem space2. Design interactions3. Map the interaction to an APIstyle4. Prototype and get feedback5. Iter...
The Problem SpaceWhy are we doing this?Who are we building it for?
InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
Consider:PlatformsOrganizationsLanguagesWho is this for?
The Problem SpaceWhat are our:Assumptions?Constraints?Shared terms and jargon?
Data GatheringHow do we learn about our targetaudience?
Interaction ModelDefine requirements:What interactions will benefit thedeveloper?What information is required tosupport th...
Interaction ModelAs a ___ I want to …
Map Interactions to an API DesignWhich style?Which formats?How do we translate interactions?
PrototypeDon’t bind to real data or backendUse something lightweight and easyto changeDo this early
Practical PrototypingWrite simple code or script in a languagethat is easy for you to implement.var express = require(expr...
Practical PrototypingConfigure an interface in a web or APIplatformGET /tasks
Practical PrototypingApply minimal securityTry writing throwaway client codeAsk target developers to write code anduse the...
Focus on the interactions that takeplace, rather than the interfaceswe expose
DX > Software Qualities
Usability Summary• Focus on the developer• Start by thinking in terms of interactions• Effective for public and private APIs
Great API design can thrive in adeveloper-centric environment
Building an API Strategy:The Developer ExperienceRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
Building an API Strategy:Architecture FoundationsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
Architecture
http://www.flickr.com/photos/naomi_pincher/3306312873/Layered Pattern
Representation Layer
Component != Connector
ComponentDatabaseFile SystemMessage QueueTransaction ManagerSource Code
Components Are Private
ConnectorWeb ServerBrowser AgentProxy ServerShared Cache
Connectors Are Public
Client ServerConnectorsComponentsThe Web
Representation Layer Representation happens in the Connector HTTP supports content negotiation- Accept- Content-Type Di...
• Data and Interface Transformation• Focus on the interface (usability)RepresentationSOAPLegacy
Security Layer
Security implementations are difficult:• Mistakes are costly• Hard to understand specifications• Performance can suffer
Don’t implement API security in the implementationEnforce security at the edgeWhere?
Caching Layer
Caching Layer
Caching Layer Caching happens EVERYWHERE HTTP supports Expiration Model and Validation Model Caching Expiration Model- ...
Orchestration Layer
• Chaining multiple calls• Aggregating and enriching data• ‘mashup’ external data with internal dataOrchestration:
Gateway Pattern Abstraction of multiple interfaces In Software Engineering: Façade Pattern Benefits:- Deliver a consist...
API GatewayGatewayAPIAPI
Restrict AccessImprove PerformanceFocus on Usability
The gateway doesn’t solve all our problems
API portalsPortal
API ManagementPortalGatewayAPIAPI
Nuts and Bolts of API Management Developer Registration Access Control API Explorer API Documentation Social Engageme...
We also apply this philosophy behind the firewall.
Architecture Summary• Use a layered architecture• Deploy a gateway for runtime• Deploy a portal for developers
Building an API Strategy:Architecture FoundationsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
Building an API Strategy:The Security ChallengeRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
The API security challenge:BalancingControl and Accessibility
IdentityAuthenticationAuthorizationAvailabilityIntegrityPrivacy
Attack Surfaces and Identities
PortalAPIDeveloperEnd UserAdministrator
PortalAPIDeveloperEnd UserAdministrator
APIEnd User
Injection AttacksUtilizing input parameters to inject data that compromisesthe security of the targeted system. Examples:...
API Attack Example:SQL Injection Attacks: APIsGET http://host.com/aresource?token=%E2%80%98or%20%E2%80%981%3D1GET http://h...
APIs May Be A Direct Conduit292HTTPServerAppServerDatabaseAppObjectsOften:• Self-documenting• Closely mapped to object space
Denial Of Service AttacksAn attack which has the objective of making a serviceunavailable to all usersExamples:- XML/JSON...
Overflow AttackIntentionally sending too much data in order to exploit atarget systems by exceeding expected boundaries.Ex...
Cross Site Scripting (XSS) AttackEmbedding code within a server that will betransmitted to users.
XSS API Example296AttackerWeb App Server(browser+APIs)Victim: WebBrowserClient<SCRIPT …>1. API injectsscript in3. Browser ...
Interception of communication between two systems.Man in the Middle Attack
OWASP Top Ten (2010 Edition)Source: http://www.owasp.org/index.php/Top_10
 Impersonating a registered application in order to accessan API resource. Examples:- Guessing application ID by brute f...
how can I protect identity on a mobile device?
…
what happens if my mobile app is impersonated?
APIEnd User
Revenue Source
What the Fudge*! Ididn’t make 10000calls yesterday!!!!!!I’m not paying that.*This is what WTF actually stands for.
I didn’t buy 1000mobile phones inRussia!I’m not paying that!
Forrester:we are moving towards a ‘zero-trust’ model
New platforms, new languages:• Ruby on Rails• Node.js• Scala• Nginx• Squid/Varnish/Traffic Manager
TLSOAuth 2Open ID Connect
OAuth provides aDelegated Authorization Framework
An imperfect analogy….
http://www.flickr.com/photos/drewleavy/5587005480
http://www.flickr.com/photos/24oranges/5791460046/
http://www.flickr.com/photos/grumbler/571106054/http://www.flickr.com/photos/roboppy/238406811/Your MoneyThis Shop Needs Y...
http://www.flickr.com/photos/drewleavy/5587005480I won’t tell.I promise!
www.flickr.com/photos/auntiep/255249516
Granting access to someone to acton your behalf.
Your resourcesThis app needs to act on your behalfYou need to grant accessto your resources
Your google+ dataThis app needs to access yourGoogle+ dataYou need to grant accessto your resources
Hi Google.I’d like to have access to a user’sdata.
Hang on, let meask…
He said yes. Here is youraccess code.
“Client” == application“Resource owner” == end-userThe first step to understanding OAuth 2:
OAuth 2 Grant Types- Authorization Code- Implicit- Resource Owner Password Credentials- Client Credentials
Authorization Code Grant326Client ApplicationResource OwnerUsingApplicationResource ServerI Wish I could accessmy resource...
Authorization Code Grant327Client ApplicationResource OwnerUsingApplicationResource Server…but I don’t trust thisapp enoug...
Authorization Code GrantInitiation328Client ApplicationResource Owner Authorization ServerResource ServerUser AgentIssue G...
Authorization Code GrantInitiation329Client ApplicationResource Owner Authorization ServerResource ServerUser AgentIssue G...
OAuth 2 Authorization Request response_type – indicates grant type client_id –application identifier redirect_uri (opti...
Authorization Code GrantResource Owner Authentication331Client ApplicationResource Owner Authorization ServerResource Serv...
Authorization Code GrantAuthorization332Client ApplicationResource Owner Authorization ServerResource ServerUser AgentDeli...
Authorization Code GrantReceipt of Authorization Code333Client ApplicationResource Owner Authorization ServerResource Serv...
Authorization Code GrantAccess Token Request334Client ApplicationResource Owner Authorization ServerResource ServerRequest...
Authorization Code GrantAccess Protected Resource335Client ApplicationResource Owner Authorization ServerResource ServerRe...
Authorization Code Grant - Summary Most Complex of OAuth 2 Grant Types Provides full OAuth 2 capability
2 vs. 3 Legged Spectrum337ThreeleggedTwolegged
OAuth 2 ChallengesIt is a framework
OAuth 2 Challenges New attack surfaces Flexible, but complex for API publishers to implement Utilizes redirection URIs ...
OpenID Connect Identity Access and Authentication (when combined with Open ID) Built on top of OAuth 2 Not tied to any ...
Open ID, Open ID Connect and OAuth 2 OAuth 2 allows an end-user to grant an application access to protected resources Ho...
 OpenID Authentication can help the server authenticate the end-user OpenID Connect provides a mechanism for the applica...
Portal
Who is using the API?How are they (mis)using it?
What would happen if the portal was exploited?
PortalAPIDeveloperEnd UserAPI
PortalAPIAdministrator
Where are the components deployed?Who owns the identity store?
PortalAPI
Summary:Challenge: Balancing Usability and SecurityOld Threats Still ExistNew Styles and Access Models create new surfaces
Building an API Strategy:The Security ChallengeRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
Upcoming SlideShare
Loading in...5
×

API Workshop Amsterdam presented by API Architect Ronnie Mitra

1,584

Published on

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.

Published in: Technology
0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,584
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
53
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide

API Workshop Amsterdam presented by API Architect Ronnie Mitra

  1. 1. Building an API Strategy:Introduction and the Business of APIsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  2. 2. API Managementvirtual cloudon-premise
  3. 3. API AcademyMike Amundsen Ronnie Mitra
  4. 4. www.apiacademy.co
  5. 5. Business DriversAPI Styles-- Break --The Developer ExperienceAPI ArchitectureSecuring APIs-- Break --Principles of URI DesignAgenda
  6. 6. What areWeb APIs?
  7. 7. Connecting things
  8. 8. Connecting computer programs
  9. 9. APIAll programmers are API designersConnections between modulesLanguage DependantAPIs are constrained by the syntax of thelanguage
  10. 10. … over the web
  11. 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. 12. Web ofDocumentsWeb ofAppsWeb ofServicesWeb ofThings
  13. 13. The web is ubiquitousAnd universally accessible
  14. 14. Publishers retain control
  15. 15. Private/Partner or Closed APIs
  16. 16. Acme Corp.APIAcme Corp.App
  17. 17. Public or Open APIs
  18. 18. Acme Corp.APIThird PartyApp
  19. 19. Priority:Lower CostPriority:Increased Adoption
  20. 20. why build an API?
  21. 21. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  22. 22. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  23. 23. Revenue Source
  24. 24. Revenue Sourcehttp://www.flickr.com/photos/inside-south-africa/485356704£0.10 per API Call
  25. 25. Revenue Source1000 calls/month5000 calls/month
  26. 26. Revenue Source500 calls/month1000 calls/month5000 calls/month
  27. 27. Revenue SourceIs your content worth paying for?
  28. 28. RevenueSourceInternal Revenue (chargeback)Cost Reduction
  29. 29. Revenue SourceStrategy Implications:• Maximize uptime andreliability• Target high revenue consumers• Competitive differentiatorsare a must
  30. 30. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  31. 31. Consumer Reach
  32. 32. Consumer Reach
  33. 33. Platforms are not forever!
  34. 34. Consumer ReachStrategy Implications:• UX driven interfaces• Specialization may berequired• Difficult to updateapplications
  35. 35. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  36. 36. MarketingAffiliate ProgramsSometimes you pay the developer.
  37. 37. MarketingDraw new visitors in.
  38. 38. Marketing
  39. 39. MarketingStay above the noise:New channelsInformation-centric marketing
  40. 40. MarketingStrategy Implications:• Terms and Services are veryimportant• Identify and reward topperformers• Limit calls and restrictaccess when needed
  41. 41. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  42. 42. InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectInnovation from within
  43. 43. InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectInnovation outside your borders
  44. 44. InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectWhen does innovation happen?
  45. 45. InnovationLight Bulb designed by Jean-Philippe Cabaroc from The Noun ProjectStrategy Implications:• Design interface for generaluse• Identify success stories• Eliminate misuse
  46. 46. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  47. 47. IntegrationBusiness driven integrationRegulatory driven integration
  48. 48. IntegrationStrategy Implications:• Reduce cost• Reduce cost• Reduce cost
  49. 49. Observational Learning:Five Famous Stories of Public APIs
  50. 50. 2000 – ebay
  51. 51. Started with a paid developer program in 2000Made it free in 2005
  52. 52. Consumer ReachMarketing
  53. 53. Large developer eco-systemLarge app eco-system
  54. 54. 25% of eBay listings come from their API!
  55. 55. salesforce2000 – salesforce
  56. 56. IntegrationRevenue Source
  57. 57. API as a cloud enabler
  58. 58. 2004 – Flickr
  59. 59. web 2.0 generationthe social evolution
  60. 60. Consumer ReachMarketing
  61. 61. The rise of self-serviceAnnounced 6 billion photos in August 2011
  62. 62. 2006 – Amazon Web Services
  63. 63. Started as an online book shop…Became a department store…now?
  64. 64. Jeff BezosConnect everythinghttp://www.flickr.com/photos/zippy/2430495092
  65. 65. 2004:Hey, why don’t we sell this?
  66. 66. Revenue Source
  67. 67. Estimated revenue:$1.5B in 2012http://wikibon.org/wiki/v/Cloud_Computing_2013%3A_The_Amazon_Gorilla_Invades_the_Enterprise
  68. 68. Twilio or stripe2007 - Twillio
  69. 69. Revenue Source
  70. 70. The API is the business
  71. 71. 100,000 developer milestone in 2012
  72. 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. 73. Original APIs are still successfulNew business models have emergedKnow your drivers – design accordinglySummary
  74. 74. Building an API Strategy:Introduction and the Business of APIsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  75. 75. Building an API Strategy:URI Style Design TipsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  76. 76. URI StyleGETPUTPOSTDELETE+ URI
  77. 77. URI StyleGET /students/1232
  78. 78. URI Style• familiar to web developers• designed for HTTP• URIs are intuitiveAdvantages
  79. 79. URI Style• limited to HTTP methods• URI design is not standard• can be ‘chatty’Trade-offs
  80. 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. 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. 82. Naming URIs• Names matter!• Establish reserved words and keywords• Names should be meaningful (to theapplication developer)
  83. 83. Naming URIs – ExamplesBad:• /Core_Items_DSTSM_1Good:• /charges
  84. 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. 85. Map InteractionsInteraction:“retrieve all my user’s messages”Object:Message
  86. 86. Resource ModelMessageTitleAuthorBodyRecipientnnn1n1nn
  87. 87. Avoid RPC NamesInteraction:“Retrieve newest messages”RPC-style Name:getNewMessages
  88. 88. Not Always EasyInteraction:“Perform a spell-check on thismessage”Object:Message?What method is ‘spell-check’?
  89. 89. Not Always EasyInteraction:“Perform a spell-check on thismessage”Object:SpellChecker
  90. 90. Types of ResourcesLots of nounsA few operators or controllers
  91. 91. Relationshipsmyapi/messagesmyapi/messages/14myapi/messages/titlemyapi.com/ronnie/messages/title
  92. 92. RelationshipsDon’t expose relationships unless theyare useful to the developerEach path segment should beactionable
  93. 93. HTTP Methods• GET• PUT• POST• DELETE• HEAD• OPTION• TRACE• CONNECT
  94. 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. 95. PUT• Write a representation• Store the entity (full replacement)• Idempotent• Example:PUT /myapi/messages/14{Message}
  96. 96. IdempotenceNo side-effects on identical callsPUT /myapi/messages/14Result: Message ReplacedPUT /myapi/messages/14Result: Message Replaced
  97. 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. 98. Why not use PUT for partial update?• Breaks HTTP specification• No defined semantic – can produceunexpected results from a devperspective
  99. 99. PATCH (Partial Update)• RFC 5789 (HTTP Patch)• Partially update an identifiedresource with the supplied entity• Example:PATCH /myapi/message/14{Partial Message}
  100. 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. 101. Challenges with PATCH• Not part of HTTP 1.1 spec• Not widely adopted inimplementations• May not be familiar to developeraudience
  102. 102. How do I implement PATCH inan environment that doesn’tsupport it?
  103. 103. PATCH WorkaroundsTurn the target data into a URI object:HTTP PUT /myapi/messages/14/title
  104. 104. PATCH WorkaroundsTunnel the patch with a custom header:X-HTTP-Method-Override: PATCH
  105. 105. PATCH WorkaroundsUse a unique URL:HTTP POST /myapi/patches/messages/14HTTP POST /myapi/messages/14/patchesHTTP POST /myapi/messages/14;patch
  106. 106. PATCH WorkaroundsUse PUT and break the specification
  107. 107. POST• Write/Process an entity• Accept entity as sub-ordinateresource• Not Idempotent• No identifier specified (factorypattern):POST /myapi/messages
  108. 108. Non-IdempotentPOST /myapi/messagesResult: Message #14 CreatedPOST /myapi/messagesResult: Message #15 Created
  109. 109. DELETE• Delete identified resource• Example:DELETE /myapi/messages/14• Idempotent
  110. 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. 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. 112. Representations - Granularity{“id” : “14”“title” : “Welcome”“body” : “Hello!”“author” : “38820”}
  113. 113. Representations - Granularity{“id” : “14”“title” : “Welcome”“body” : “Hello!”“author” : [ “id” : “38820”,“firstName” : “Ronnie” ]}
  114. 114. Representations – GranularityConsiderationsChattiness vs. LatencyFrequency of changeInteraction (what data is needed?)
  115. 115. Retrieve a Collection of Data• Example: “Retrieve all storelocations”• GET /shops
  116. 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. 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. 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. 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. 120. Returning Collections• array of results• all properties and child elements?• collection responses can be BIG!
  121. 121. Pagination• Just like websites – break data upinto manageable ‘pages’
  122. 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. 123. Pagination• offset + count mechanism/api/resource?offset=10&count=20• client app dictates page size10 30• client calculates offset and count forpages
  124. 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. 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. 126. Field Projection•‘property selection’, ‘zooming’• Collections can be too big for someclient• Allow client to select properties inrepresentations
  127. 127. Field Projection - ExampleGET /myapi/messages?fields=title,body{[{“id”: “1”, “title” : “hi!”, “body” :“hello”}…]}
  128. 128. Linking• Use links as identifiers{[{“id”: “/myapi/messages/13”},{“id”: “/myapi/messages/14”}]}
  129. 129. LinkingAdvantages:• Developer doesn’t need to constructURI• URIs can change!Trade-offs:• Query parameters increasecomplexity
  130. 130. Implementing LinkingLots of Standards:• HAL• SIREN• Collection + JSON• ATOM• XML LINKING• HTML
  131. 131. Implementing LinkingLots of APIs just do this:{“link_name” : “link”}
  132. 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. 133. Content Types• XML• JSON• HTML
  134. 134. XML• Not the same as SOAP / Tunnel Style• Widely used (AJAX, mobile, server)• W3C Standard, RFC 3023
  135. 135. JSON• Usage rising• Popular amongst next-gen developers• JavaScript everywhere• RFC 4627
  136. 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. 137. HTML• Hypermedia content type• Web Form: application/x-www-form-urlencoded• Useful for simple name/value pairinput• Easy for developers to implement
  138. 138. Selecting a Representation• Content Negotiation• HTTP Accept Header• URI based• /myapi/messages.xml
  139. 139. Status Codes• 1xx: Informational• 2xx: Success• 3xx: Redirection• 4xx: Client Error• 5xx: Server Error
  140. 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. 141. Status CodesClient libraries should handle statuscodes and act in an expected manner
  142. 142. Error Handling• You might include an applicationlevel error code• Definitely Include a human readableerror message
  143. 143. A Few Interactions
  144. 144. Asynchronous RequestClient Resource202 AcceptedFire and Forget
  145. 145. Asynchronous RequestClient Resource202 Accepted<link href=“…” rel=“status”/>StatusResource200 OK<status>complete</status><link href=“…” rel=“result”/>
  146. 146. Server CallbackClient ResourceRegister200 OK200 OKNotify
  147. 147. Server Event (Long Poll)Client ResourceBlock and Wait200 OKHTTP Abuse
  148. 148. Optimizations
  149. 149. Optimizations• Mobile and device platforms haveunique bandwidth constraints• Transport Level (HTTP)• API Design
  150. 150. HTTP Optimizations• Compression• Negotiation (Accept-Encoding)• Example:• Is JSON more efficient than XML?Accept-Encoding: compress, gzip
  151. 151. HTTP Optimizations• Pipelining• Multiple requests without waitingfor response• Supported in HTTP 1.1 (persistentconnections)• Idempotent actions only
  152. 152. API Design OptimizationsReduce data size (pagination, fieldprojection)Reduce number of calls:• Composition• RPC batch• Caching
  153. 153. CompositionURI style APIs can be chattyCombine interactions and expose onthe serverExample:/myapi/composer
  154. 154. BatchingURI style APIs can be chattyCombine and invoke calls on the clientCan be complicated for the developer
  155. 155. CachingMany forms of cachingHTTP Caching avoids use of networkWidely supported
  156. 156. Adaptive Responses• Provide responses that are the bestfit for the calling application•Examples:• Reduced granularity• Different defaults• UI Driven
  157. 157. URI Design Summary• Some standards, but lots of choices• Design with developer in mind• Consistency and structure areimportant
  158. 158. Building an API Strategy:URI Style Design TipsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  159. 159. Building an API Strategy:The Developer ExperienceRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  160. 160. designing APIs can be difficult
  161. 161. http://www.flickr.com/photos/nirufe/3469696707?
  162. 162. UsabilityReliabilitySimplicitySecurityEtc…Software Qualities
  163. 163. Focus on the developer experience(dx)
  164. 164. Interaction DesignBill Moggridge
  165. 165. UsabilityHuman-Computer-InteractionUser Experience DesignGoal Oriented Design
  166. 166. http://www.flickr.com/photos/58754750@N08/5541472392/
  167. 167. A user-centric view of design.
  168. 168. Well designed products are easierto use.
  169. 169. Good design matters for Web APIstoo.
  170. 170. Priority:Lower CostPriority:Increased Adoption
  171. 171. PortalAPI
  172. 172. PortalAPIDeveloperEnd UserAdministrator
  173. 173. PortalAPI
  174. 174. This is obvious right?
  175. 175. Why is this difficult to do in practice?
  176. 176. Reason #1We project our own perspective.
  177. 177. Reason #2We project our own biases.
  178. 178. Never use SOAP?Why?
  179. 179. Consider keyboards…
  180. 180. http://www.flickr.com/photos/yvettemn/139890573/
  181. 181. http://www.flickr.com/photos/jonathanpberger/7126054997/
  182. 182. http://www.flickr.com/photos/novemberborn/286773981/
  183. 183. OR
  184. 184. It doesn’t matter that you don’t likeSOAP.
  185. 185. What matters is what your developerbase thinks!(and what your objective is)
  186. 186. Reason #3We make bad assumptions.
  187. 187. API publishers are also developers.
  188. 188. “I built a mobile app once.”
  189. 189. Reason #4We lack the time, money orincentive for good design
  190. 190. “Best practices”, patterns andstandards become shortcuts
  191. 191. Am I RESTfull enough?
  192. 192. So, how can we do better?
  193. 193. Developer-centric design requireseffort and diligence.
  194. 194. Design with the developer in mind.
  195. 195. Ask them.
  196. 196. • Interviews• Surveys• Listen (blogs, presentations,tweets)
  197. 197. +
  198. 198. • Observe• Prototype• Analyze Historical Data
  199. 199. Consider all aspects of the DX:RegistrationSecurityTroubleshootingLearningInterface Style
  200. 200. A Good DX = A Good System
  201. 201. Tunnel StyleURI StyleHypermedia StyleEvent Driven Style
  202. 202. RegistrationLazy RegistrationSocial IntegrationPersonalization
  203. 203. Development Activity Cycle1. Learn2. Code3. Implement4. Test5. Fix
  204. 204. PortalAPILearnCodeTest
  205. 205. APILearnTest
  206. 206. API explorers and “livedocumentation” can shorten thegap between visibility andfeedback.
  207. 207. LearningWADLs and WSDLs are niceBut provide real documentation for humans!Hypermedia =/= zero documentation
  208. 208. TLSOAuth 2Open ID Connect
  209. 209. SecuritySecurity can hurt UsabilityBut… security can also improve theoverall experience!We need to think about the system as awhole
  210. 210. Complexity• Sometimes complexity is necessary –that is ok• Enough features to meetrequirements• Don’t hurt the DX – use structureand modularity
  211. 211. Structure and ConsistencyDefine a consistent Message Structure{ “Response” : {“Errors” : {}}}
  212. 212. Structure and ConsistencyDefine consistent standards for:• Naming• Collection structure• Content negotiation• Links
  213. 213. Structure and ConsistencyEnforcing standards requiresorganizational disciplineEspecially difficult in largeorganizations!
  214. 214. ModularityPartition APIs into modules orproductsFrom a DEVELOPER perspective!
  215. 215. “Frictionless” integrationHigh rates of adoptionLow cost integrationWe want:
  216. 216. Behaviour DesignBJ Fogg
  217. 217. Visitor Invested Developer
  218. 218. JoyVisitorInvested DeveloperJoyJoy
  219. 219. A Sample DX Based Design Process
  220. 220. 1. Define the problem space2. Design interactions3. Map the interaction to an APIstyle4. Prototype and get feedback5. Iterate
  221. 221. The Problem SpaceWhy are we doing this?Who are we building it for?
  222. 222. InnovationConsumer ReachRevenue SourceMarketingIntegrationLight Bulb designed by Jean-Philippe Cabaroc from The Noun Project
  223. 223. Consider:PlatformsOrganizationsLanguagesWho is this for?
  224. 224. The Problem SpaceWhat are our:Assumptions?Constraints?Shared terms and jargon?
  225. 225. Data GatheringHow do we learn about our targetaudience?
  226. 226. Interaction ModelDefine requirements:What interactions will benefit thedeveloper?What information is required tosupport the interaction?
  227. 227. Interaction ModelAs a ___ I want to …
  228. 228. Map Interactions to an API DesignWhich style?Which formats?How do we translate interactions?
  229. 229. PrototypeDon’t bind to real data or backendUse something lightweight and easyto changeDo this early
  230. 230. Practical PrototypingWrite simple code or script in a languagethat is easy for you to implement.var express = require(express),app = express();var port = 8080;app.listen(port);app.get("/tasks", function(req, res) {res.status(200).send(‘<response><tasks><task><name>Pick up Kai</name><priority>1</priority></tasks></response>’);}
  231. 231. Practical PrototypingConfigure an interface in a web or APIplatformGET /tasks
  232. 232. Practical PrototypingApply minimal securityTry writing throwaway client codeAsk target developers to write code anduse the APIMake quick changes and try it again
  233. 233. Focus on the interactions that takeplace, rather than the interfaceswe expose
  234. 234. DX > Software Qualities
  235. 235. Usability Summary• Focus on the developer• Start by thinking in terms of interactions• Effective for public and private APIs
  236. 236. Great API design can thrive in adeveloper-centric environment
  237. 237. Building an API Strategy:The Developer ExperienceRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  238. 238. Building an API Strategy:Architecture FoundationsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  239. 239. Architecture
  240. 240. http://www.flickr.com/photos/naomi_pincher/3306312873/Layered Pattern
  241. 241. Representation Layer
  242. 242. Component != Connector
  243. 243. ComponentDatabaseFile SystemMessage QueueTransaction ManagerSource Code
  244. 244. Components Are Private
  245. 245. ConnectorWeb ServerBrowser AgentProxy ServerShared Cache
  246. 246. Connectors Are Public
  247. 247. Client ServerConnectorsComponentsThe Web
  248. 248. Representation Layer Representation happens in the Connector HTTP supports content negotiation- Accept- Content-Type Differing clients (user-agents) === differing representations- Desktop- Browser- Tablet- Smartphone Be prepared to support multiple representations
  249. 249. • Data and Interface Transformation• Focus on the interface (usability)RepresentationSOAPLegacy
  250. 250. Security Layer
  251. 251. Security implementations are difficult:• Mistakes are costly• Hard to understand specifications• Performance can suffer
  252. 252. Don’t implement API security in the implementationEnforce security at the edgeWhere?
  253. 253. Caching Layer
  254. 254. Caching Layer
  255. 255. Caching Layer Caching happens EVERYWHERE HTTP supports Expiration Model and Validation Model Caching Expiration Model- Expires- Cache-Control: max-age Validation Model- Last-Modified- Etag, If-Match Be prepared to support caching for both client and server Squid, Varnish, Nginx, MemCacheD, NSURLConnection etc.
  256. 256. Orchestration Layer
  257. 257. • Chaining multiple calls• Aggregating and enriching data• ‘mashup’ external data with internal dataOrchestration:
  258. 258. Gateway Pattern Abstraction of multiple interfaces In Software Engineering: Façade Pattern Benefits:- Deliver a consistent experience- Centralize API functionalityhttp://martinfowler.com/eaaCatalog/gateway.html
  259. 259. API GatewayGatewayAPIAPI
  260. 260. Restrict AccessImprove PerformanceFocus on Usability
  261. 261. The gateway doesn’t solve all our problems
  262. 262. API portalsPortal
  263. 263. API ManagementPortalGatewayAPIAPI
  264. 264. Nuts and Bolts of API Management Developer Registration Access Control API Explorer API Documentation Social Engagement Tracking and Reporting
  265. 265. We also apply this philosophy behind the firewall.
  266. 266. Architecture Summary• Use a layered architecture• Deploy a gateway for runtime• Deploy a portal for developers
  267. 267. Building an API Strategy:Architecture FoundationsRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  268. 268. Building an API Strategy:The Security ChallengeRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  269. 269. The API security challenge:BalancingControl and Accessibility
  270. 270. IdentityAuthenticationAuthorizationAvailabilityIntegrityPrivacy
  271. 271. Attack Surfaces and Identities
  272. 272. PortalAPIDeveloperEnd UserAdministrator
  273. 273. PortalAPIDeveloperEnd UserAdministrator
  274. 274. APIEnd User
  275. 275. Injection AttacksUtilizing input parameters to inject data that compromisesthe security of the targeted system. Examples:- SQL Injection- Command Injection- Code Injection- Argument Injection
  276. 276. API Attack Example:SQL Injection Attacks: APIsGET http://host.com/aresource?token=%E2%80%98or%20%E2%80%981%3D1GET http://host.com/aresource?token=‘ or ‘1=1select * from tokens where token = ‘’ or ‘1=1’;
  277. 277. APIs May Be A Direct Conduit292HTTPServerAppServerDatabaseAppObjectsOften:• Self-documenting• Closely mapped to object space
  278. 278. Denial Of Service AttacksAn attack which has the objective of making a serviceunavailable to all usersExamples:- XML/JSON parser attacks- Jumbo messages- Server overload
  279. 279. Overflow AttackIntentionally sending too much data in order to exploit atarget systems by exceeding expected boundaries.Examples: Buffer Overflow Cash Overflow
  280. 280. Cross Site Scripting (XSS) AttackEmbedding code within a server that will betransmitted to users.
  281. 281. XSS API Example296AttackerWeb App Server(browser+APIs)Victim: WebBrowserClient<SCRIPT …>1. API injectsscript in3. Browser loadscontent withembedded script2. Server fails toperform FIEO: FilterInput, Escape OutputAPI
  282. 282. Interception of communication between two systems.Man in the Middle Attack
  283. 283. OWASP Top Ten (2010 Edition)Source: http://www.owasp.org/index.php/Top_10
  284. 284.  Impersonating a registered application in order to accessan API resource. Examples:- Guessing application ID by brute force- Retrieving application ID by sniffing traffic- Cracking application to retrieve application IDApp Spoofing
  285. 285. how can I protect identity on a mobile device?
  286. 286.
  287. 287. what happens if my mobile app is impersonated?
  288. 288. APIEnd User
  289. 289. Revenue Source
  290. 290. What the Fudge*! Ididn’t make 10000calls yesterday!!!!!!I’m not paying that.*This is what WTF actually stands for.
  291. 291. I didn’t buy 1000mobile phones inRussia!I’m not paying that!
  292. 292. Forrester:we are moving towards a ‘zero-trust’ model
  293. 293. New platforms, new languages:• Ruby on Rails• Node.js• Scala• Nginx• Squid/Varnish/Traffic Manager
  294. 294. TLSOAuth 2Open ID Connect
  295. 295. OAuth provides aDelegated Authorization Framework
  296. 296. An imperfect analogy….
  297. 297. http://www.flickr.com/photos/drewleavy/5587005480
  298. 298. http://www.flickr.com/photos/24oranges/5791460046/
  299. 299. http://www.flickr.com/photos/grumbler/571106054/http://www.flickr.com/photos/roboppy/238406811/Your MoneyThis Shop Needs Your MoneyYou need to grant accessto your money
  300. 300. http://www.flickr.com/photos/drewleavy/5587005480I won’t tell.I promise!
  301. 301. www.flickr.com/photos/auntiep/255249516
  302. 302. Granting access to someone to acton your behalf.
  303. 303. Your resourcesThis app needs to act on your behalfYou need to grant accessto your resources
  304. 304. Your google+ dataThis app needs to access yourGoogle+ dataYou need to grant accessto your resources
  305. 305. Hi Google.I’d like to have access to a user’sdata.
  306. 306. Hang on, let meask…
  307. 307. He said yes. Here is youraccess code.
  308. 308. “Client” == application“Resource owner” == end-userThe first step to understanding OAuth 2:
  309. 309. OAuth 2 Grant Types- Authorization Code- Implicit- Resource Owner Password Credentials- Client Credentials
  310. 310. Authorization Code Grant326Client ApplicationResource OwnerUsingApplicationResource ServerI Wish I could accessmy resources throughthis application…
  311. 311. Authorization Code Grant327Client ApplicationResource OwnerUsingApplicationResource Server…but I don’t trust thisapp enough to give itmy credentials.
  312. 312. Authorization Code GrantInitiation328Client ApplicationResource Owner Authorization ServerResource ServerUser AgentIssue GETrequest viaUser-Agent
  313. 313. Authorization Code GrantInitiation329Client ApplicationResource Owner Authorization ServerResource ServerUser AgentIssue GETrequest viaUser-Agentresponse_typeclient_idredirect_uriscopestate
  314. 314. OAuth 2 Authorization Request response_type – indicates grant type client_id –application identifier redirect_uri (optional) – address which the UA can use to respond to client scope (optional) – space delimitted string: what the client wants to do state (optional)– opaque string used to defeat CSRF attacks Sample Authorization GET URL:https://azserver/oauth2/authorize?response_type=code&client_id=my_id&state=state&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback
  315. 315. Authorization Code GrantResource Owner Authentication331Client ApplicationResource Owner Authorization ServerResource ServerUser AgentSendUserAuthenticationForm?Authenticate
  316. 316. Authorization Code GrantAuthorization332Client ApplicationResource Owner Authorization ServerResource ServerUser AgentDeliverGrantScreen???ApproveGrantRequest
  317. 317. Authorization Code GrantReceipt of Authorization Code333Client ApplicationResource Owner Authorization ServerResource ServerUser AgentRedirectUser-AgentClientApplication! RedirectedToClientApplicationcodestate302
  318. 318. Authorization Code GrantAccess Token Request334Client ApplicationResource Owner Authorization ServerResource ServerRequestAccessTokenReturnAccessTokenand OptionalRefresh Tokengrant_typecoderedirect_uriclient_id200AZ CodeAZ Code
  319. 319. Authorization Code GrantAccess Protected Resource335Client ApplicationResource Owner Authorization ServerResource ServerRequestResourceUsingApplicationReturnResource200
  320. 320. Authorization Code Grant - Summary Most Complex of OAuth 2 Grant Types Provides full OAuth 2 capability
  321. 321. 2 vs. 3 Legged Spectrum337ThreeleggedTwolegged
  322. 322. OAuth 2 ChallengesIt is a framework
  323. 323. OAuth 2 Challenges New attack surfaces Flexible, but complex for API publishers to implement Utilizes redirection URIs (should be validated with strong rules) Poor implementations will be exposed (see Facebook) Not a solution to user authentication
  324. 324. OpenID Connect Identity Access and Authentication (when combined with Open ID) Built on top of OAuth 2 Not tied to any single vendor or identity provider
  325. 325. Open ID, Open ID Connect and OAuth 2 OAuth 2 allows an end-user to grant an application access to protected resources However:- The authorization server must still authenticate the end-user- The client application is unable to determine information about the end-userClient ApplicationResource Owner Authorization ServerUser AgentSendUserAuthenticationForm?Authenticate
  326. 326.  OpenID Authentication can help the server authenticate the end-user OpenID Connect provides a mechanism for the application to learn about the end-userOpen ID, Open ID Connect and OAuth 2Client ApplicationResource Owner Authorization ServerUser AgentSendOpenIDAuthenticationFormAuthenticateRetrieve UserInformationOpenIDResourceServer
  327. 327. Portal
  328. 328. Who is using the API?How are they (mis)using it?
  329. 329. What would happen if the portal was exploited?
  330. 330. PortalAPIDeveloperEnd UserAPI
  331. 331. PortalAPIAdministrator
  332. 332. Where are the components deployed?Who owns the identity store?
  333. 333. PortalAPI
  334. 334. Summary:Challenge: Balancing Usability and SecurityOld Threats Still ExistNew Styles and Access Models create new surfaces
  335. 335. Building an API Strategy:The Security ChallengeRonnie MitraPrincipal API Architect - EuropeLayer 7 API Academy
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×