140 likes | 211 Views
How to write a great API (and why you need to have one) Presentation by: Daniel Chilcott Managing Director, Flowgear @Flowgear @ DanielChilcott www.Flowgear.net/developers www.Flowgear.net/challenge. Wed 17 Apr 2PM. Why you need an API. For your product
E N D
How to write a great API (and why you need to have one) Presentation by: Daniel Chilcott Managing Director, Flowgear @Flowgear @DanielChilcott www.Flowgear.net/developers www.Flowgear.net/challenge Wed 17 Apr 2PM
Why you need an API • For your product • SaaS & Cloud adoption are forcing use of API’s • Consumers expect integration • In enterprise • Simplifies projects with customers and vendors (EDI) Introduction
Benefits: API’s are Developer UI • Structured form of integration • Ensure business logic & validation applied • Compatibility & Abstraction • Stay relevant Introduction
Picking a methodology Library (SDK) • Stateful • Can’t be easily called remotely • Can be faster (fewer transport layers) • Example: Pastel Evolution Web API • Stateless • Easy to call remotely • Supports wider range of use-cases • Example: Pick n Pay Which Technology?
Picking a transport SOAP • Cluttered payload • Self-describing (WSDL) • XML only REST • Lean on data • No self-describing standard (can use WSDL2 or WADL) • XML & JSON • Example: Twitter Which Technology?
More about REST • Uses full spectrum of HTTP codes • 200 OK • 400 Bad Request • 403 Forbidden • 404 Not Found • Common Mistake: Placing verbs in URL: • api.domain.com/getCustomer/?id=123 • GET api.domain.com/customer/?id=123 Which Technology?
Serialisation Options XML • Bloated • Less readable • Supports namespaces • Support attributes JSON • Cleaner • More readable • No namespaces • No attributes Which Technology?
Authentication • Authenticate as a user or require an API token • Set a session or token expiry policy • Absolute timeout • Last-touch timeout • Negotiate version • Alternative to separate methods for different versions Features OAuth • Provide delegated authority to 3rd party apps • No credential sharing • Granular permissions Protect Credentials • Use a directory service (AD) or OR • Salt, Hash, Repeat!
Versioning • Negotiate version on session commencement • Parition versions https://api.twitter.com/1.1/statuses/user_timeline.json https://api.twitter.com/1/statuses/user_timeline.json • Be backward compatible • Add new methods • Add new fields • No rename/delete Features
Completeness Cover all actions (CRUD) on all objects • Grow it over time • Live your own API Support Bulk Queries • Often overlooked – dev’s forced to query database • Make it efficient and fast • Support paged requests Features
Supporting the Community Provide great documentation • PDF’s are good for sequential reading, not reference guides • Build a Wiki • Create more than a reference guide, create a Getting Started and topical Tutorials • Provide a test harness & SDK • Make your devprogram free Features Facebook Good Documentation DocuSign Great Test Harness Technical Competence 1 x Certified Engineer 1 x Certified Technician
Handle Abuse Make sure you’ve covered all the bases • Verify new users (email, SMS, captcha) • Require authentication for all calls • Apply bandwidth limiting • Apply rate limiting • Apply concurrent request limiting • Don’t forget injection vulnerabilities Features
Web API Demo Web API is a platform for building RESTful API’s in Visual Studio DEMO Getting Started
Thank You ! Daniel Chilcott daniel@Flowgear.net @Flowgear @DanielChilcott Section Heading