design first api's with raml and soapui
DESCRIPTION
Daniel Feist, Architect @ Mulesoft Matti Hjelm, SoapUI Product Manager @ SmartBear In this workshop we'll develop a real-world API together using RAML to define the interface and SoapUI to simulate and test the interface and API consumer experience before even thinking about the implementation. In doing this we'll cover the powerful design-first features of RAML as well as the tooling available to facilite this approach. We’ll also cover the mocking and prototyping features of SoapUI. Finally we'll implement, deploy and test our new API in a production environment.TRANSCRIPT
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!