simple.raml

#%RAML 0.8

title: World Music API
baseUri: http://example.api.com/{version}
version: v1
mediaType: application/json
traits:
  paged:
    queryParameters:
      pages:
        description: The number of pages to return
        type: number
/songs:
  get:
    is: [ paged ]
    queryParameters:
      genre:
        description: filter the songs by genre
    responses:
        200:
          body:
            application/json:
              schema: |
                {
                  "$schema": "http://json-schema.org/schema",
                  "type": "array",
                  "description": "A list of songs",
                  "items": {
                    "$ref": "song.json"
                  }
                }
  /{songId}:
    post:
      body:
        application/json:
          schema: |
            { "$schema": "http://json-schema.org/schema",
              "type": "object",
              "description": "A canonical song",
              "properties": {
                "title":  { "type": "string" },
                "artist": { "type": "string" }
              },
              "required": [ "title", "artist" ]
            }
    get:
      responses:
        200:
          body:
            application/json:
              schema: |
                { "$schema": "http://json-schema.org/schema",
                  "type": "object",
                  "description": "A canonical song",
                  "properties": {
                    "title":  { "type": "string" },
                    "artist": { "type": "string" }
                  },
                  "required": [ "title", "artist" ]
                }
              example: |
                {
                  "title": "Wish You Were Here",
                  "artist": "Pink Floyd"
                }
            application/xml:
    delete:
      description: |
        This method will *delete* an **individual song**