For every API, start by defining which version of RAML you are using, and then document basic characteristics of your API - the title, version, and baseURI.

RAML allows you to define patterns using traits, resourceTypes, and securitySchemes, and then use them within a API to minimize repetition.

Externalize those patterns, store them on the web, and import them with an !include.

Easily define resources and methods, then add as much detail as you want. Apply traits and other patterns, or add parameters and other details specific to each call.

Describe expected responses for multiple mime-types and specify schemas and examples for each one. Schemas and examples can be defined in-line, or externalized with !include.

Write human-readable, markdown-formatted descriptions throughout your RAML spec, or include entire markdown documentation sections at the root.

                    
                      
  1. #%RAML 0.8
  2. title: World Music API
  3. baseUri: http://example.api.com/{version}
  4. version: v1
  5. traits:
  6. - paged:
  7. queryParameters:
  8. pages:
  9. description: The number of pages to return
  10. type: number
  11. - secured: !include http://raml-example.com/secured.yml
  12. /songs:
  13. is: [ paged, secured ]
  14. get:
  15. queryParameters:
  16. genre:
  17. description: filter the songs by genre
  18. post:
  19. /{songId}:
  20. get:
  21. responses:
  22. 200:
  23. body:
  24. application/json:
  25. schema: |
  26. { "$schema": "http://json-schema.org/schema",
  27. "type": "object",
  28. "description": "A canonical song",
  29. "properties": {
  30. "title": { "type": "string" },
  31. "artist": { "type": "string" }
  32. },
  33. "required": [ "title", "artist" ]
  34. }
  35. application/xml:
  36. delete:
  37. description: |
  38. This method will *delete* an **individual song**
Copied!