RAML

Designing RESTful APIs with RAML

Transcript

1. RAML Designing RESTful APIs with RAML Damijan Cavar @cavar_si
4. Why RAML? • community driven • technology agnostic • built for readability • big ecosystem • supported by companies like VMWare, Cisco ...
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
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
7. Security scheme • defined on the root level of specification • supported schemes: OAuth 1.0 OAuth 2.0 Basic Authentication Digest Authentication
8. Resources
9. Define responses
10. Generating the documentation Your APIs are only as good as the documentation that comes with them. Invest time in getting docs right.
11. Testing
12. Mocking • we can develop client ahead of API • one of the runners is Osprey Mock Service
13. Useful links • http://raml.org/ • https://github.com/raml-apis • https://anypoint.mulesoft.com/apiplatform/popular/#/portals • http://www.sitepoint.com/raml-restful-api-modeling-language/ • http://docs.raml.org/apis
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
15. Questions ? Damijan Cavar @cavar_si