RAML - APIs By Design
Upcoming SlideShare
Loading in...5
×

Like this? Share it with your network

Share

RAML - APIs By Design

  • 2,271 views
Uploaded on

My talk (first given at HTML5 Dev Conference October 2013) about API design and RAML. See http://raml.org for more info.

My talk (first given at HTML5 Dev Conference October 2013) about API design and RAML. See http://raml.org for more info.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
2,271
On Slideshare
2,267
From Embeds
4
Number of Embeds
1

Actions

Shares
Downloads
57
Comments
0
Likes
4

Embeds 4

https://twitter.com 4

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. RAML – APIs By Design #RAML Uri Sarid CTO, MuleSoft @MuleSoft @usarid
  • 2. APIs: The Cat's Meow
  • 3. Ultimate Buzz for Creatively-lazy Developers build on someone else's work… who's? 14000 12000 open APIs 10000 8000 6000 4000 2000 0 2005 2006 2007 2008 2009 2010 2011 2012 Source: 2013
  • 4. Modularity, Encapsulation, Specialization yes, even Service-Oriented Architecture!  eCommerce  products  shopping cart  checkout  billing  shipping  social  graph  posting  geolocation  city data  weather  attractions  businesses  collaboration  documents  notifications  forums  analytics  traffic  logs  NLP  sales  marketing  demographics  SFA  social
  • 5. The API Economy Is Big and It's Now >13,000 Open APIs Enterprise APIs 1,000,000s
  • 6. APIs and me
  • 7. My Experience: consumer portal utility back-office software
  • 8. The API Contract Is Critical • tells consumer devs what they'll get • tells implementer devs what to deliver • enables parallel development • ensures they'll meet in the end
  • 9. My Experience: Barnes & Noble / the layer cake of APIs Don't expose dirty laundry  users products orders  invoices
  • 10. At MuleSoft connectivity
  • 11. The traditional enterprise sits comfortably behind the firewall Packaged apps Custom apps The Traditional Enterprise Databases
  • 12. Welcome to the New Enterprise SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  • 13. Connect backend SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  • 14. Backend to SaaS SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  • 15. Everything needs to connect SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  • 16. The Anypoint Platform: integration on-premises and cloud SaaS Cloud platforms Social Anypoint Platform Mobility and Devices Customers / Partners / Suppliers Mule Studio Anypoint Connectors Anypoint DataMapper Enterprise Mgmt DataSense Packaged apps Business Insight Custom apps Big Databases / Big Files
  • 17. The Anypoint Platform: integration on-premises and cloud 1,000s 100s SaaS 1,000,000s Cloud platforms 100,000s Social 1,000,000,000s Anypoint Platform Mobility and Devices Customers / Partners / Suppliers Mule Studio Anypoint Connectors Anypoint DataMapper Enterprise Mgmt DataSense Packaged apps Business Insight Custom apps Big Databases / Big Files
  • 18. The Anypoint Platform for APIs SaaS Cloud platforms Social Anypoint Platform Design/Dev Portal API Manager APIkit Anypoint Connectors Mobility and Devices API Gateway Studio Customers / Partners / Suppliers Anypoint DataMapper Business Insight Enterprise Mgmt DataSense Packaged apps Custom apps Big Databases / Big Files
  • 19. An Opinionated Approach to API Success
  • 20. The Key to API Success? how? • • • • design for them iterate quickly model cleanly and consistently engage
  • 21. Design For Your Users UI  UX Capture Feedback API  APX
  • 22. Focus on the Interface: The Contract  where consumers touch you  your front door, your lobby, your façade  how you want to be seen; your brand  versioned more carefully than code  better interfaces  better code  an organizing principle; alignment forcing function  the ultimate testing surface
  • 23. What kind of interface do we want? 1. Describe APIs simply and clearly 2. Design APIs easily and soundly 3. Engage users in compelling ways
  • 24. Practically-RESTful APIs • • • • • • nouns: resources, described by URI paths verbs: HTTP methods metadata: HTTP headers responses: HTTP status codes representations: appropriate media types in the body use hypermedia – not necessarily, not yet
  • 25. What Do People Do Today?
  • 26. WADL
  • 27. Reverb Swagger
  • 28. Mashery IOdocs
  • 29. Google Discovery Docs
  • 30. Apiary Blueprint
  • 31. Verdict: manifest structure capture patterns humanly writeable let's try harder…
  • 32. Start From Scratch? Really???
  • 33. No Need to Start From Scratch! • • • • • • • well-known superset of JSON optimized for human readability great for hierarchies cruft-free broad tooling base extensible-ish broad tooling base
  • 34. Introducing: RAML RESTful API Modeling Language A new open spec for RESTful APIs that's as clean and as structured as REST itself the RAML Workgroup: raml.org
  • 35. RAML: How Clean? How Structured? Take what you would have typed yourself… /users: get: description: post: description: /users/{userId}: get: description: put: description: delete: description: Get a collection of users Create a new user in the collection Get a single user Update a single user Delete a single user
  • 36. RAML: How Clean? How Structured?
  • 37. RAML: How Clean? How Structured?
  • 38. RAML: How Clean? How Structured? resource type schema trait
  • 39. 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
  • 40. Patterns: Resource Types externalizable inheritance pull in traits parametrize
  • 41. Patterns: Method-level traits mix-ins
  • 42. Patterns: body schemas XML schema JSON schema or just use good ol' form data: examples
  • 43. RAML for Real-Time APX Design
  • 44. raml.org
  • 45. What's next?  open-source tooling; host it too (e.g. on APIhub)  growing library of API specs in RAML (e.g. on APIhub)  converters  client generators  server frameworks (e.g. MuleSoft APIkit; node.js)  testing frameworks  mocking services (e.g. on APIhub)  <insert your ideas here>  evolve RAML spec (RAML workgroup)
  • 46. One More Thing…