RAML

 RAML

Designing RESTful APIs with RAML

3e1b8a0d3349eb49fc92f43340ab59ea?s=128

Damijan Cavar

March 01, 2016
Tweet

Transcript

  1. 2.
  2. 3.
  3. 4.

    Why RAML? • community driven • technology agnostic • built

    for readability • big ecosystem • supported by companies like VMWare, Cisco ...
  4. 5.

    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
  5. 6.

    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
  6. 7.

    Security scheme • defined on the root level of specification

    • supported schemes: OAuth 1.0 OAuth 2.0 Basic Authentication Digest Authentication
  7. 10.

    Generating the documentation Your APIs are only as good as

    the documentation that comes with them. Invest time in getting docs right.
  8. 11.
  9. 12.

    Mocking • we can develop client ahead of API •

    one of the runners is Osprey Mock Service
  10. 14.

    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