5 Keys to API Design - API Days Paris 2013
Upcoming SlideShare
Loading in...5

5 Keys to API Design - API Days Paris 2013






Total Views
Views on SlideShare
Embed Views



2 Embeds 8

http://mysoaone.blogspot.com.au 7
http://mysoaone.blogspot.com 1



Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

5 Keys to API Design - API Days Paris 2013 5 Keys to API Design - API Days Paris 2013 Presentation Transcript

  • 5 Keys to API Design Daniel Feist @dfeist Principal Architect, MuleSoft @MuleSoft
  • Me?
  • Me?
  • Me?
  • Me?
  • APIs: The Cat's Meow
  • The New Enterprise All contents Copyright © 2013, MuleSoft Inc. 7
  • The New Enterprise SaaS Cloud platforms Social Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps Big Databases / Big Files
  • The New Enterprise 1,000s 100s SaaS Cloud platforms Social 1,000,000,000s 100,000s Mobility and Devices Customers / Partners / Suppliers Packaged apps 1,000,000s Custom apps Big Databases / Big Files
  • The New Enterprise SaaS Social Cloud platforms Open web APIs Mobility and Devices Customers / Partners / Suppliers B2B APIs Product APIs Internal APIs Packaged apps Custom apps The New Enterprise Databases
  • API Design
  • #1 The Contract is Critical
  • The API Contract Is Critical •  tells consumer devs what they'll get •  tells implementer devs what to deliver •  enables parallel development •  ensures they'll meet in the end
  • The Contract is Critical ü  where consumers touch you ü  your front door, your lobby, your façade ü  how you want to be seen; your brand ü  versioned more carefully than code ü  better interfaces è better code ü  an organizing principle; alignment forcing function ü  the ultimate testing surface
  • What kind of contract do we want? 1.  Describe APIs simply and clearly 2.  Design APIs easily and soundly
  • What kind of contract do we want? Document your API? or Model your API?
  • #2 Design to Delight
  • The Key to API Success? how? •  •  •  •  design for them iterate quickly model cleanly and consistently gather feedback
  • #3 Think APX not API
  • Design For Your Users UI à UX Valida te API à APX Capture Feedback
  • Think APX! This is a long-lived interface, ladies and gentlemen Don't expose dirty laundry ! users products orders è invoices Craft it for your users: what will they love?
  • #4 Use Patterns
  • Pattern Lifecycle Define Share Reuse
  • Types of Patterns •  Resource Types •  Collection •  Collection Member •  Document •  Traits •  Secure •  Paged
  • #5 Engage Developers
  • Engage Developers •  Social Tools •  Rate, discuss •  Provide feedback •  Interactive Console •  Prototyping Tools
  • What Do People Do Today?
  • WADL
  • Reverb Swagger
  • Mashery IOdocs
  • Google Discovery Docs
  • Apiary Blueprint
  • Verdict: manifest structure capture patterns humanly writeable let's try harder…
  • Start From Scratch? Really???
  • No Need to Start From Scratch! •  •  •  •  •  •  well-known superset of JSON optimized for human readability great for hierarchies cruft-free broad tooling base extensible-ish
  • RAML RESTful API Modeling Language A new open spec for RESTful APIs that's as clean and as structured as REST itself the RAML Workgroup: raml.org
  • RAML: How Clean? How Structured?
  • RAML: Clean & Structured.
  • RAML: Reuse resource type schema trait
  • Covers Full HTTP optional version in baseUri template URIs query parameters headers (on request and response) response per status code example (and schema) per media type
  • Patterns: Resource Types externalizable inheritance pull in traits parametrize
  • Patterns: Method-level traits mix-ins
  • Patterns: body schemas XML schema JSON schema or just use good ol' form data: examples
  • Patterns: security schemes username/password; cleartext or use digest end user allows app to access their data better to put token in header, not query the OAuth multi-step dance
  • What's next? q growing library of API specs in RAML (e.g. on APIhub) q converters (import WADL, Swagger etc.) q client generators q server frameworks (e.g. MuleSoft APIkit; node.js) q JAX-RS Support q testing frameworks q mocking services (e.g. on APIhub) q <insert your ideas here> q evolve RAML spec (RAML workgroup)
  • Interesting?
  • Thank you!