• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
5 Keys to API Design - API Days Paris 2013
 

5 Keys to API Design - API Days Paris 2013

on

  • 371 views

 

Statistics

Views

Total Views
371
Views on SlideShare
363
Embed Views
8

Actions

Likes
1
Downloads
11
Comments
0

2 Embeds 8

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

Accessibility

Categories

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.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
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!