iSyndica - Building an API
Download as PPTX, PDF0 likes328 views
The document discusses guidelines for building good APIs, including keeping API calls atomic, documenting the API well, and using code generation. It also covers common API security types like developer keys and OAuth, noting the document's focus is on building a good API for iSyndica that is secure and works well across platforms. The document encourages having fun in the process and acknowledges there is no single perfect API design.
iSyndica - Building an API
- 1. iSyndicaBuilding an APIHackerspace.sg, April 20th 2010
- 2. Good API DesignIt’s a great asset.Or a liability.
- 3. What makes an API ‘Good’?It just works.
- 5. Three Key GuidelinesGreatExampleseBayFacebookFlickrGoogle DataTwitterDocument well.
- 6. Three Key Guidelines.NET: T4Ruby:RgenPython: Cog, CheetahJava: XDocletCode generation is your friend.
- 7. API Security TypesDeveloper KeyUsername/PasswordDigestToken
- 8. Our Choice
- 10. Have FunThere’s no “Perfect API”.
Editor's Notes
- #3: An API can be a great asset or a liabilityGood API’s capture trafficOf-boarding cost can be prohibitiveBad API’s can be a huge drain in terms of supportOnce an API is published and in production, it becomes hard to change.
- #4: Ease of useEasy to learnEasy to add functionalityGets the job done
- #5: API's need to be Stateless - Every request needs to contain all of the information necessary to service the request. Every API should be atomic - It does one logical operation and one alone and doesn't rely on any sequential calls.API’s should abstract the implementation detailUse self explanatory name.Avoid ambiguous overloading
- #6: Documentation – It’s a necessary evil, there are too many API’s out there that don’t have enough usable documentation.Be consistent with naming conventions throughout the API.Modularize your code and try to think in terms of interfaces and not implementation types
- #7: Attempt to incorporate the patterns already existing in the development platform of your choice.Try to reduce “boiler plate” code. Cut & Paste is very error prone. Use Code generation where ever possible.Our 80/20: write code 20% of the time.
- #8: Developer Key – Unique developer identifier sent as part of every call. Not so secure.Username / Password – Username & Password sent as part of every call. Not so secure unless using HTTPS which is 90% slower than HTTPDigest – Using an security algorithm to stamp a call with a digest for authentication. Fairly secure and easy to implement.Token – Using an identification token
- #9: OAuth is token based authentication mechanisms that standardizes secure API authorization for desktops & web applicationsOAuth stake holdersProviders – Software applications that provide a service on the web i.e. API enabled websites/web-services. For eq. Facebook, Flickr etcUsers – Users of a service, average joe’s who own an account with the providersConsumers –3rd party Software applications that proxy for the users with the providers. For eqFacebook Mobile, iSyndica VDSAdvantagesOnly the provider sees your username / passwordThe token is easily tracked by the provider and as a user you can limit/revoke the permissionUse of a secret key makes phishing the token useless.DisadvantagesComplex implementation
- #10: No cleartext username and password ever stored, Username & Password are sent over HTTPS – Slow but secureOauth Loop is instantaneous, No need for the user to go through complexOAuth loops
- #11: API design isn’t easy but incredibly funAdds incredible valueA group effortThere is no “Perfect API” that fits all the requirement.
- #12: API design isn’t easy but incredibly funAdds incredible valueA group effortThere is no “Perfect API” that fits all the requirement.