RAML 1.0: Design, Build, Test, Document, & Share Your API

l All contents Copyright © 2014, MuleSoft Inc.

RAML 1.0Design, Build, Test, Document, Share

by mike stowe


• API Fanatic

• Open Source Contributor

• Author, Speaker, Consultant

• 10+ years hacking Professional Code

• Dev Relations Manager at MuleSoft

About Me

@mikegstowe


Let’s build an API

l All contents Copyright © 2014, MuleSoft Inc.4

...people are fairly good at short-term design, and usually awful at long-term design.”

“

-Dr. Roy Fielding


How we build APIs

We need an API…


How we build APIs

WE need an API…


How we build APIs

API Style/ Design


How we build APIs

User Stories


How we build APIs

Start Coding


How we build APIs

Timeline Issues


How we build APIs

Add More Resources


How we build APIs

Let’s Collaborate*


How we build APIs

Write lots of code… FAST


How we build APIs

Drop Stories Lwill be next “version”


How we build APIs

Skip planning needs, we can focus on this later


How we build APIs

Testing/ Stage!!!


How we build APIs

Production!!!


How we build APIs

Document API


How we build APIs

Create SDKs, Mobile Apps, etc


How we build APIs

Find Bugs, Inconsistencies, Issues


How we build APIs

Add New Features/ Fix Bugs…


How we build APIs

How do we do this without breaking everything???


How we build APIs

Add New Features? What changed?


When you think about it… the API Design Process isn’t just inefficient...


It’s Broken.


We have to learn to rethink differently.”“- Andrew Curioso, Cloud Architect


What if you could controlthe entire API Lifecycle, reduce design flaws, and eliminate redundancies?


Empowering architects, developers, tech writers, and support to work more efficiently by doing what they’re best at.


• RAML is an open source specification for DESCRIBING APIs

• RAML is surrounded by an open source community with over

100 projects in 12 programming languages

What is RAML?


• RAML is backed by a working group consisting members from

MuleSoft, Akana, Cisco, Intuit, Airware, VMware,

ProgrammableWeb, and Angular.js

• RAML is used commercially by thousands of companies

including Spotify, Cisco, VMware, PBS, Sonic, and more

Who is RAML?


• Akana, AWS, CA Technologies, MuleSoft,

Restlet, Software AG, Gelato, APImatic, REST

United, API Fortress, API Metrics, API Science,

Parasoft, PAW, Postman, SandBox, SmartBear,

Oracle, SAP…

Who supports RAML?


• You can define your API in just a few lines of code

• You can see what it would look like as you go

• You can quickly prototype it for devs to try

• You can quickly make tweaks/ changes

• You can easily document your API

• You can let developers try your API online

• You can let developers interact with your and other APIs

• Generate SDKs/ client libraries for your API

What can you do with RAML?


• You can use and force design patterns

• You can reuse code (libraries, traits, resourceTypes, overlays)

More Importantly…

resourceTypes:- collection:

description: Collection of available <<resourcePathName>> in Jukebox.get:description: Get a list of <<resourcePathName>>.responses:

200:body:

application/json:example: |

<<exampleCollection>>


What does it look like?


What Does RAML Look Like?

#%RAML 1.0title: World Music APIbaseUri: http://example.api.com/{version}version: v1/playlists:

get:responses:

200:body:

application/json:example: |{ “playlistID” : 1, “playlistName” : “My Awesome Playlist”, “genre” : “top40”,“songs” : 40

}


The RAML API Designer


Writing RAML


Writing RAML

Getting Started


Writing RAML: Getting Started

#%RAML 1.0title: World Music APIbaseUri: http://example.api.com/{version}version: v1


Writing RAML

Creating Resources


Writing RAML: Creating Resources

#%RAML 1.0title: World Music APIbaseUri: http://example.api.com/{version}version: v1/playlists:

description: This is my descriptionget:description: get a collection of playlists

/{id}:description: access a specific playlist by IDget:

description: get a playlist by ID


Writing RAML

Schemas & Examples


Creating RAML: Schemas & Examples

…/playlists:

get:responses:

200:body:

application/json:example: |

{ “playlistID” : 1, “playlistName” : “My Awesome Playlist”, “genre” : “top40”,“songs” : 40

}


Creating RAML: Schemas & Examples

…/playlists:

get:responses:

200:body:

application/json:example: !include examples/example.jsonschema: !include schemas/example.json

application/xml:example: !include examples/example.xmlschema: !include schemas/example.xml


Writing RAML

ResourceTypes


Creating RAML: ResourceTypes

#%RAML 1.0title: World Music API

resourceTypes:collection:get:responses:200:body:application/json:

example: <<exampleResp>>schema: <<schemaResp>>

500:body:application/json:example: <<errorResp>>


Creating RAML: ResourceTypes

#%RAML 1.0title: World Music API…

/playlists:type:collection:exampleResp: {"example" : "provided"}schemaResp: {"schema" : "provided"}errorResp: {"error" : "provided"}


Writing RAML

Data Types


Creating RAML: Data Types

#%RAML 1.0title: World Music API…

types:playlist:type: objectproperties:name:

type: stringsongs:

type: object[]


Creating RAML: Data Types

…/playlists:get:responses:200:body:application/json:type: playlist


Writing RAML

Libraries


Creating RAML: Libraries

#%RAML 1.0 Library

resourceTypes:collection:

types:playlist:type: object

properties:name:

type: stringsongs:

type: object[]


Creating RAML: Libraries

#%RAML 1.0…uses:

playlist: libraries/playlist.raml

/playlists:type:playlist.collection:

get:responses:200:body:application/json:

type: playlist.playlist


Writing RAML

Overlays


Creating RAML: Overlays

#%RAML 1.0 Overlay

/playlists:description: Add in a description over the

original Spec


Creating RAML: Overlays

#%RAML 1.0 Extension

baseUri: http://adminApi.domain.com

/playlists:delete:

description: only admins get access to this


Do it Yourself

Get the Code at:

bit.ly/2aOiKzl


Community Tools


Community Tools

Design


API Workbench (offline)API Designer (online)


Community Tools

Build


Community Tools

Test


Community Tools

Document


RAML to HTML (Node.js)


RAML 2 HTML for PHP


Griffin by Spotify


Community Tools

Share


REST United

APIMatic.io

API Notebook


Learn More about RAML 1.0

RAML website:http://raml.org

Twitter: @ramlapi

Pick up our Pocket Guide to RAML 1.0before you leave J


One Final Thought


• Define your API before Coding

• Use Design Patterns/ Code Reuse

• Mock and get User Feedback

• Make Necessary Changes

• Start Coding – to the Spec

• DO NOT DEVIATE!

Use Spec Driven Development


Hybrid Approach

Design Development

Continuous, fluid, changeable Static… No turns


The Agile Design Cycle


Learn More about RAML 1.0

RAML website:http://raml.org

Twitter: @ramlapi

Pick up our Pocket Guide to RAML 1.0before you leave J


THANK YOU!!!mulesoft.com/restbook


@MuleDevmulesoft.com/restbook

RAML 1.0: Design, Build, Test, Document, & Share Your API

Technology

Transcript of RAML 1.0: Design, Build, Test, Document, & Share Your API