ddd (delight-driven development) of apis with raml
DESCRIPTION
Uri Sarid, CTO, MuleSoft API-first development is an approach in which the APIs between systems are designed and validated without requiring any implementation, and then form the requirements for implementing the API provider and consumer(s). RAML, the RESTful API Modeling Language (http://raml.org), is a relatively new open format for specifying web APIs. It’s distinguished by focusing on writeability as well as readability, on minimality and elegance, and on enabling and encouraging reusability and consistency of APIs. This makes RAML an ideal basis for API-first development. In particular, RAML is a fitting foundation for API initiatives whose success is predicated on delighting their customers: the developers who will be consuming the API. In this talk I’ll introduce RAML, API-first development, API design, and some tools that not only produce delightful APIs but are also delightful on their own. I hope you find this useful whether you’re just documenting existing APIs, looking to improve your APIs and their lifecycle, or embarking on new API initiatives.TRANSCRIPT
![Page 1: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/1.jpg)
Uri Sarid RAML Workgroup Member
CTO, MuleSoft
#RAML
@usarid
@MuleSoft
DDD (Delight-Driven Development)
of APIs with RAML
![Page 2: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/2.jpg)
Web APIs: The Cat's Meow
![Page 3: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/3.jpg)
Ultimate buzz for creatively-lazy developers
Build on someone else's work… who's?
![Page 4: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/4.jpg)
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
![Page 5: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/5.jpg)
Front-stage in business
tied to business objectives
power big initiatives:
• mobile • new revenues
• innovation
budgeted and owned
regarded as products
![Page 6: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/6.jpg)
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
![Page 7: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/7.jpg)
API Maxims
![Page 8: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/8.jpg)
Imperatives for success
need for speed
> developers rule...
![Page 9: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/9.jpg)
Get the core right
docs
consistency
testing
mocking + live
console client
factory
server framework
lifecycle
detailed usecases
API source code
![Page 10: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/10.jpg)
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
![Page 11: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/11.jpg)
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
![Page 12: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/12.jpg)
#1 imperative to API success
• design for them
• model cleanly and consistently
• iterate quickly
• …(behind the scenes)
• engage compellingly
![Page 13: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/13.jpg)
UI à UX
API à APX
API success by analogy
Application Programming Experience
API spec
![Page 14: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/14.jpg)
The API Spec
![Page 15: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/15.jpg)
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
![Page 16: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/16.jpg)
/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…
![Page 17: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/17.jpg)
RAML: How Clean? How Structured?
![Page 18: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/18.jpg)
RAML: How Clean? How Structured?
![Page 19: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/19.jpg)
RAML: How Clean? How Structured?
resource type schema
trait
![Page 20: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/20.jpg)
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
![Page 21: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/21.jpg)
Patterns: Resource Types
externalizable
inheritance
pull in traits
parametrize
![Page 22: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/22.jpg)
Patterns: Method-level traits
mix-ins
![Page 23: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/23.jpg)
Patterns: body schemas
or just use good ol' form data:
XML schema
JSON schema
examples
![Page 24: DDD (Delight-Driven Development) Of APIs With RAML](https://reader033.vdocuments.mx/reader033/viewer/2022042816/559458ed1a28ab732f8b4822/html5/thumbnails/24.jpg)
RAML for Real-Time APX Design