Upgrade to Pro — share decks privately, control downloads, hide ads and more …



Designing RESTful APIs with RAML

Damijan Cavar

March 01, 2016

Other Decks in Programming


  1. Why RAML? • community driven • technology agnostic • built

    for readability • big ecosystem • supported by companies like VMWare, Cisco ...
  2. Raml basic #%RAML 0.8 title: GitHub API version: v3 baseUri:

    https://api.github.com mediaType: application/json schemas: - User: schema/user.json Users: schema/users.json Org: schema/org.json Orgs: schema/orgs.json
  3. Resource types and traits • removes the need for repetition

    by inheritance • with traits we can decorate the resource to add properties traits: - secured: usage: Apply this to any method that needs to be secured description: Some requests require authentication. queryParameters: access_token: description: Access Token type: string example: ACCESS_TOKEN required: true
  4. Security scheme • defined on the root level of specification

    • supported schemes: OAuth 1.0 OAuth 2.0 Basic Authentication Digest Authentication
  5. Generating the documentation Your APIs are only as good as

    the documentation that comes with them. Invest time in getting docs right.
  6. Mocking • we can develop client ahead of API •

    one of the runners is Osprey Mock Service
  7. Takeaways • Use RAML to design your API before implementing

    it • You will get documentation as a free bonus • You can mock, test api easily • With RAML you can develop client and API in parallel