Cra$ing Consumable APIs
Sumedha Rubasinghe, WSO2 November, 2012
with WSO2 API Manager
Cra$ing Consumable APIs
Cra$ing APIs | Consumable APIs
Cra$ing APIs | Consumable APIs
Cra$ing APIs
• API Design • API Interface • Documenta3on • Versioning • Adver3sing • Community Building
• Feedback/Discussion Channel • Communica3on/no3fica3on • Tooling • Lifecycle
API Design • Joshua Bloch, How To Design A Good API And Why It MaJers, hJp://
www.youtube.com/watch?v=aAb7hSCtvGw
API Interface
• Contract between you & outside world o Honor it – all the 3me
• Input formats • Output formats • Availability • Performance figures • QoS
DocumentaEon
• Most important channel between your APIs & developers
• Has to be, o Up-‐to-‐date o Descrip3ve o Sufficient examples o Reader friendly o Intui3ve o Searchable
API Versioning
• Evolu3on !! • Backward compa3bility of,
o Func3onality • Forward compa3bility of
o Access Tokens o Rates/ThroJling agreements
• Different versioning mechanisms
API Versioning
• Version as query parameter o Ne`lix -‐ hJp://api.ne`lix.com/catalog/3tles/series/70023522?v=1.5
o Google Data API -‐ “GData-‐Version: X.0″₺ or “v=X.0″₺ • Version as part of URI
o Salesforce -‐ hJps://na1.salesforce.com/services/data/v20.0/sobjects/Account/
o TwiJer -‐ hJps://api.twiJer.com/1.1/statuses/men3ons_3meline.json
API Versioning
• Version as date in URI o Twillo (hJp://www.twilio.com/docs/api/rest/making-‐calls) -‐ /2010-‐04-‐01/Accounts/{AccountSid}/Calls
• Version as a Custom HTTP Header • Version as part of Accept Header • Version as part of Content-‐Type
Community
• Ac3ve user community is an ‘asset’ • Protect them • Encourage them • Facilitate them
o Forums o Ra3ngs o Discussion boards/wikis o Compe33ons o Offers o Early adaptor/beta users o Advisory panels
CommunicaEon/NoEficaEon
• Constantly communicate with your community o Upcoming features o Offers/compe33ons, etc.
• Support for automa3c no3fica3ons o Subscrip3on capabili3es o Selec3on/filtering capabili3es
Tooling Support
• SDKs • CLIs • Stubs / generators
API Lifecycle
• An API can pass through mul3ple states • Can be one of,
• CREATED • PUBLISHED • DEPRECATED • RETIRED • BLOCKED
• Integra3on with a complete governance lifecycle – upcoming feature
API Lifecycle
API Lifecycle
API Lifecycle
API Lifecycle
API Lifecycle
Service vs API Lifecycle
Cra$ing APIs | Consumable APIs
Consumable APIs
• Adver3sing • Subscrip3ons • Authoriza3on
o Mechanism
• Access Token o Lifecycle o Management
• Extensible • Collec3ng Sta3s3cs • Monitoring
Consumable APIs
• Metering • Billing/Mone3za3on • Deployment • Scaling • Maintenance
o Running Repairs o End of life process
Support for AdverEsing/MarkeEng
• Display on a store !!! • Accessible via a URL • Start Adver3sing
o Compe33ons o Press o Blogs o Email campaigns
https://store.apicultur.com/
SubscripEon
Subscribers
Authentication Mechanisms
• HTTP Basic authen3ca3on/SSL • Form based authen3ca3on/SSL • HTTP Digest authen3ca3on • OAuth
• OAuth 1.0 • OAuth 2.0
• SSO • Refer Prabath’s “Securing APIs” session
Authentication
Authentication
Authentication
Authentication
Access Token
• OAuth2 Token • Lifecycle
• Expired -‐> Refresh Token • Blocked • New version of API • Deprecated API
• Management
API call with an access token
Extensible
• Custom sign up UIs • Sign up for Store • Sign up for publisher
• Custom workflow extensions • Sign up flow for store/publisher • API Subscrip3on flow
• Custom representa3ons of UI data • Theming • Powered by backend data APIs -‐> JSON
• Custom Data Summariza3on formats
https://store.apicultur.com/
Collecting Statistics
• During API Invoca3ons….
Event Stream Definition
Statistics Storage
Metering
• API Access Sta3s3cs -‐> Metering data • Metering Data -‐> Billing System • Exten3ons
• Ability to create custom summary data • Apache Hive Scripts
• Mul3ple data source support
Monetization
• Decision for having an API should be backed by a clear objec3ve. Can be one of, • Developer adop3on • Community building • Revenue genera3on • And many more..
• Revenue Genera3on …. o Requires a billing model
Billing Models
• Per-‐transac3on charging • Subscrip3on-‐based charging • Volume-‐based charging • Zero-‐ra3ng
Billing Models
Source: John Musser,ProgrammableWeb, http://www.slideshare.net/jmusser/open-apis-whats-hot-whats-not-12506063
Billing Models
Source: John Musser,ProgrammableWeb, http://www.slideshare.net/jmusser/open-apis-whats-hot-whats-not-12506063
Billing Generation
Deployment - Standalone
Deployment - Standalone
Scaling
Maintenance
• Regular Monitoring • Access paJerns • Load averages • Geographical Distribu3on
• Re3ring • Depreca3on Process
• No3fica3on • Migra3on
• End of Life
In return…
• Yet another product • Increasing
• Revenue • Direct/In-‐direct • Mone3ze enterprise data
• Community/Developer Innova3on • Awareness • Partner Integra3on
Next in line..