5 Keys to API Design Daniel Feist

Principal Architect, MuleSoft

@MuleSoft

@dfeist

Me?

Me?

Me?

Me?

APIs: The Cat's Meow

7 All contents Copyright © 2013, MuleSoft Inc.

The New Enterprise

The New Enterprise

SaaS

Packaged apps Custom apps Big Databases / Big Files

Social Cloud platforms

Customers / Partners / Suppliers

Mobility and Devices

SaaS

Packaged apps Custom apps Big Databases / Big Files

Social Cloud platforms

Customers / Partners / Suppliers

Mobility and Devices

100,000s

100s 1,000s

1,000,000s

1,000,000,000s

The New Enterprise

SaaS

Packaged apps Custom apps Databases

Social Cloud platforms

Customers / Partners / Suppliers Mobility and Devices

The New Enterprise

Internal APIs

B2B APIs

Open web APIs

Product APIs

The New Enterprise

API Design

#1 The Contract is Critical

•  tells consumer devs what they'll get

The API Contract Is Critical

•  tells implementer devs what to deliver

•  ensures they'll meet in the end

•  enables parallel development

ü 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

The Contract is Critical

1. Describe APIs simply and clearly

2. Design APIs easily and soundly

What kind of contract do we want?

Document your API?

What kind of contract do we want?

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

Valid

ate

Capture Feedback

UI à UX

API à APX

Design For Your Users

Think APX!

Don't expose dirty laundry

users

products

orders invoices

è!

Craft it for your users: what will they love?

This is a long-lived interface, ladies and gentlemen

#4 Use Patterns

Pattern Lifecycle

Define Share Reuse

•  Resource Types •  Collection •  Collection Member •  Document

•  Traits •  Secure •  Paged

Types of Patterns

#5 Engage Developers

•  Social Tools •  Rate, discuss •  Provide feedback

•  Interactive Console

•  Prototyping Tools

Engage Developers

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???

•  well-known superset of JSON •  optimized for human readability •  great for hierarchies •  cruft-free •  broad tooling base •  extensible-ish

No Need to Start From Scratch!

RAML

A new open spec for RESTful APIs that's as clean and as structured as REST itself

RESTful API Modeling Language

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

or just use good ol' form data:

XML schema

JSON schema

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

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)

What's next?

Interesting?

Thank you!