ddd (delight-driven development) of apis with raml

Uri Sarid RAML Workgroup Member

CTO, MuleSoft

#RAML

@usarid

@MuleSoft

DDD (Delight-Driven Development)

of APIs with RAML

Web APIs: The Cat's Meow

Ultimate buzz for creatively-lazy developers

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

Reached critical mass

q eCommerce q products q shopping cart q checkout q billing q shipping

q social q graph q posting

q geolocation q city data q weather q attractions q businesses

q collaboration q documents q notifications q forums

q analytics q traffic q logs q NLP q sales

q marketing q demographics q SFA q social

Front-stage in business

tied to business objectives

power big initiatives:

•  mobile •  new revenues

•  innovation

budgeted and owned

regarded as products

Practically-RESTful APIs

•  nouns: resources, described by URI paths •  verbs: HTTP methods •  metadata: HTTP headers •  responses: HTTP status codes •  representations: body with appropriate media types •  hypermedia? – technically req'd for ReST, but uncommon

SOAP often seen as an outgoing tech, even in enterprises

REST dominates public, mobile, new APIs; SOAP still strong in heavier, B2B APIs

API Maxims

Imperatives for success

need for speed

> developers rule...

Get the core right

docs

consistency

testing

mocking + live

console client

factory

server framework

lifecycle

detailed usecases

API source code

Ideally: API-first development

•  tells consumer devs what they'll get

•  tells implementer devs what to deliver

•  ensures they'll meet in the end

•  enables parallel development

API-first development - steps

1.  Plan: what are you trying to achieve?

2.  Design and validate

3.  Lock down spec

4.  Implement

5.  Deploy – manageably

6.  Operate & engage

7.  Look to next version…

Design and validate

#1 imperative to API success

•  design for them

•  model cleanly and consistently

•  iterate quickly

•  …(behind the scenes)

•  engage compellingly

UI à UX

API à APX

API success by analogy

Application Programming Experience

API spec

The API Spec

So Without Further Ado…

ESTful PI odeling anguage

http://raml.org

Jason Harmon Head of API Design PayPal

John Musser Founder ProgrammableWeb API Science

Samar Choudhary Lead Architect, AISG Cisco

Uri Sarid CTO MuleSoft

Peter Rexer Sr Platform Product Manager Box

Ivan Lazarov Chief Enterprise Architect Intuit

Misko Hevery Project Founder AngularJS

The RAML Workgroup:

Tony Gullotta Director of Technology SOA Software

/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…


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

RAML for Real-Time APX Design