API First Development with

RAML and SoapUI

Daniel Feist @dfeist Principal Architect, MuleSoft

Matti Hjelm Product Manager, SmartBear

Me?

API Testing and Mocking

Use Case

•  (Fictitious) Global Shipping & Logistics Company •  Shipping via Truck/Ship/Air from Warehouses •  Two tiers of customers:

•  Pay as you go (small medium business) •  Premium Customers (e.g. Amazon, Macy’s, etc.)

•  Mythical looking for new ways to increase revenue •  Currently use FTP integration for partner enablement

Mythical Logistics Inc

•  New revenue channel - Perishable Inventory •  Unused shipping capacity •  Last minute deals •  Low rates for premium subscription customers •  Operational efficiency

•  API Initiative •  Build new API for perishable inventory quote/shipment •  Leverage existing RateFinder Service for quote •  Enable mobile apps with new API

New Business Opportunity

6

New ‘Business Shipping API’

/quote

RateFinder API

Perishable Inventory

Application /shipment

Business Shipping API Consumer apps API Implementation

Premium

API Development

Lifecycle

API Development Lifecycle

Test   Build   Publish   Operate  Design   Engage  Mock  

Design

•  The Client Application?

•  The Service Implementation?

So, what should we ‘Design’ first?

ü  Interface is most important part of your API

ü where consumers touch you

ü your front door, your lobby, your façade

ü your brand

ü Good API helps achieve Adoption

ü  Enables parallel development.

ü  Allows you to start testing early.

Neither! The API interface..

Model your API..

•  design for them your users •  iterate quickly •  model cleanly and consistently •  gather feedback •  test!

Valid

ate

Capture Feedback

API à APX

Collaborate on API Design

Business Shipping API

Tom Shafii Product Manager, API’s

Mythical Logistics Inc.

Jason Hall Senior Developer

Mythical Logistics Inc.

Design: The Contract

WSDL?

* *

What then?

* *

Format Strength Reusable Patterns

Sponsor

WADL (XML)

Swagger (JSON)

IODocs (JSON)

RestDoc (JSON)

API Blueprint

(Markdown)

RAML (YAML)

RestDoc

WADL

Swagger

IOdocs

API Blueprint

Design:

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

Design Demo

Demo

Collaborate on API Design

Business Shipping API

Tom Shafii Product Manager, API’s

Mythical Logistics Inc.

Jason Hall Senior Developer

Mythical Logistics Inc.

Mock

Why Mock?

ü  To try it out!

ü Minimal investment

ü Find design issues early

ü  Provide early access to API for feedback.

ü  Start building clients

Demo - Mock

Prototype / Iterate

Business Shipping API

Tom Shafii Product Manager, API’s

Mythical Logistics Inc.

Jason Hall Senior Developer

Mythical Logistics Inc.

Ruby Mobile App Developer, Amazon Inc.

Feedback

New Reqs.

Mock

Test

Manual Testing

Testing for Real..

ü  Scenario based testing

ü  Automated

ü  Reusable (design, dev, prod)

ü  Test Performance

Demo - Test

First, Test your Mock API

Business Shipping API

Jason Hall Senior Developer

Mythical Logistics Inc.

Mock

API Tests

•  SoapUI testing the API •  Import RAML •  Mock the API •  Test the API (Mocked)

•  Improve the API •  Add cancel (verb DELETE)

•  Use the mock from client (Android)

Demo

Testing actually improves Design

Mock Design Test

Build

Demo

Test your API in Development

Business Shipping API

Jason Hall Senior Developer

Mythical Logistics Inc.

API Implementation

API Tests

Publish

Demo - Publish

Test your API in Production

Business Shipping API API

Implementation

Ruby Rails Mobile App Developer, Amazon Inc.

Invoke API

Operate

•  Contract Enforcement •  Security •  Analytics •  Monetization

API Management

Demo - Management

Monitoring: Quality in production

•  Monitoring •  Synthetic vs RUM (real user monitoring) •  Use Alertsite •  Samma testsuite i design, utveckling, pre prod test

and post deploy •  Root cause APM tools

•  Debug API in production

Demo - Monitoring

API Operation

Business Shipping API API

Implementation

Invoke API

Engage

•  Having a delightful API!

•  Prototyping tools •  Interactive Console •  Notebook

•  Social Tools •  Rate, discuss •  Provide feedback •  Forum

Engage Developers

Demo – API Portal

Demo - API Notebook

API Development Lifecycle

Test   Build   Publish   Operate  Design   Engage  Mock  

Thank You!