raml - apis by design

RAML – APIs By Design

Uri Sarid

CTO, MuleSoft

#RAML

@usarid

@MuleSoft

APIs:The Cat's Meow

build on someone else's work… who's?

Ultimate Buzz for Creatively-lazy Developers

2005 2006 2007 2008 2009 2010 2011 2012 20130

2000

4000

6000

8000

10000

12000

14000

Source:

open APIs

yes, even Service-Oriented Architecture!

Modularity, Encapsulation, Specialization

eCommerceproductsshopping cartcheckoutbillingshipping

socialgraphposting

geolocationcity dataweatherattractionsbusinesses

collaborationdocumentsnotifications forums

analytics traffic logsNLPsales

marketingdemographicsSFAsocial

The API Economy Is Big and It's Now

1,000,000s

>13,000 Open APIs

Enterprise APIs

APIs and me

My Experience:

utility back-office software

consumer portal

• 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

My Experience: Barnes & Noble /

Don't expose dirty laundry

users

products

ordersinvoices

the layer cake of APIs

At MuleSoft

connectivity

Packaged apps Custom apps Databases

The Traditional Enterprise

The traditional enterprisesits comfortably behind the firewall

Welcome to the New Enterprise

SaaS

Packaged apps Custom apps Databases

SocialCloud platforms

Customers / Partners / Suppliers Mobility and Devices

The New Enterprise

Connect backend

SaaS

Packaged apps Custom apps Databases

SocialCloud platforms

Customers / Partners / Suppliers Mobility and Devices

The New Enterprise

Backend to SaaS

SaaS

Packaged apps Custom apps Databases

SocialCloud platforms

Customers / Partners / Suppliers Mobility and Devices

The New Enterprise

Everything needs to connect

SaaS

Packaged apps Custom apps Databases

SocialCloud platforms

Customers / Partners / Suppliers Mobility and Devices

The New Enterprise

The Anypoint Platform:integration on-premises and cloud

SaaS

Packaged apps Custom apps Big Databases / Big Files

SocialCloud platforms

Customers / Partners / Suppliers

Mobility and Devices

Anypoint Platform

BusinessInsight

EnterpriseMgmt

Mule Studio

Anypoint DataMapper

DataSense

Anypoint Connectors

The Anypoint Platform:integration on-premises and cloud

SaaS

Packaged apps Custom apps Big Databases / Big Files

SocialCloud platforms

Customers / Partners / Suppliers

Mobility and Devices

Anypoint Platform

BusinessInsight

EnterpriseMgmt

Mule Studio

Anypoint DataMapper

DataSense

Anypoint Connectors

100,000s

100s1,000s

1,000,000s

1,000,000,000s

The Anypoint Platform for APIs

SaaS

Packaged apps Custom apps Big Databases / Big Files

SocialCloud platforms

Customers / Partners / Suppliers

Mobility and Devices

Anypoint Platform

BusinessInsight

EnterpriseMgmt

Studio

APIkit

Anypoint DataMapper

DataSense

API Gateway

API Manager

Design/Dev Portal

Anypoint Connectors

An Opinionated Approach to API Success

DELIGHT YOUR USERS!

The Key to API Success?

how?

• design for them• iterate quickly• model cleanly and consistently• engage

Codify

Req

’s

Design API

Val

idat

e

Publish

CaptureFeedback

UI UX

API APX

Design For Your Users

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

Focus on the Interface: The Contract

1. Describe APIs simply and clearly

2. Design APIs easily and soundly

3. Engage users in compelling ways

What kind of interface do we want?

NOT documentation

NOT annotations in implementation

• nouns: resources, described by URI paths• verbs: HTTP methods• metadata: HTTP headers• responses: HTTP status codes• representations: appropriate media types in the body• use hypermedia – not necessarily, not yet

Practically-RESTful APIs

a few words

about

REST…

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• broad tooling base

No Need to Start From Scratch!

YAML

Introducing: 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

/users: get: description: Get a collection of users post: description: Create a new user in the collection/users/{userId}: get: description: Get a single user put: description: Update a single user delete: description: Delete a single user

RAML: How Clean? How Structured?

Take what you would have typed yourself…

RAML: How Clean? How Structured?

RAML: How Clean? How Structured?

RAML: How Clean? How Structured?

resource typeschema

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

RAML for Real-Time APX Design

DEMO

raml.org

open-source tooling; host it too (e.g. on APIhub) growing library of API specs in RAML (e.g. on APIhub) converters client generators server frameworks (e.g. MuleSoft APIkit; node.js) testing frameworks mocking services (e.g. on APIhub) <insert your ideas here>

evolve RAML spec (RAML workgroup)

What's next?

One More Thing…

NOTEBOOK DEMO