RAML - APIs By Design

3,678
-1

Published on

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

Published in: Technology
1 Comment
12 Likes
Statistics
Notes
No Downloads
Views
Total Views
3,678
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
102
Comments
1
Likes
12
Embeds 0
No embeds

No notes for slide

RAML - APIs By Design

  1. 1. RAML – APIs By Design #RAML Uri Sarid CTO, MuleSoft @MuleSoft @usarid
  2. 2. APIs: The Cat's Meow
  3. 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. 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. 5. The API Economy Is Big and It's Now >13,000 Open APIs Enterprise APIs 1,000,000s
  6. 6. APIs and me
  7. 7. My Experience: consumer portal utility back-office software
  8. 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. 9. My Experience: Barnes & Noble / the layer cake of APIs Don't expose dirty laundry  users products orders  invoices
  10. 10. At MuleSoft connectivity
  11. 11. The traditional enterprise sits comfortably behind the firewall Packaged apps Custom apps The Traditional Enterprise Databases
  12. 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. 13. Connect backend SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  14. 14. Backend to SaaS SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  15. 15. Everything needs to connect SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  16. 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. 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. 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. 19. An Opinionated Approach to API Success
  20. 20. The Key to API Success? how? • • • • design for them iterate quickly model cleanly and consistently engage
  21. 21. Design For Your Users UI  UX Capture Feedback API  APX
  22. 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. 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. 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. 25. What Do People Do Today?
  26. 26. WADL
  27. 27. Reverb Swagger
  28. 28. Mashery IOdocs
  29. 29. Google Discovery Docs
  30. 30. Apiary Blueprint
  31. 31. Verdict: manifest structure capture patterns humanly writeable let's try harder…
  32. 32. Start From Scratch? Really???
  33. 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. 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. 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. 36. RAML: How Clean? How Structured?
  37. 37. RAML: How Clean? How Structured?
  38. 38. RAML: How Clean? How Structured? resource type schema trait
  39. 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. 40. Patterns: Resource Types externalizable inheritance pull in traits parametrize
  41. 41. Patterns: Method-level traits mix-ins
  42. 42. Patterns: body schemas XML schema JSON schema or just use good ol' form data: examples
  43. 43. RAML for Real-Time APX Design
  44. 44. raml.org
  45. 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. 46. One More Thing…
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×