kinlane
3/9/2014 - 2:47 AM

Products API - RAML

Products API - RAML

#%RAML 0.8
---
#===============================================================
#  Products API - RAML example
#  References:
#    - RAML Specification - http://raml.org/spec.html
#    - RAML Projects - http://raml.org/projects.html
#    - RAML Tools  - http://www.apihub.com/raml-tools
#===============================================================
title: Products API
version: v0.1
#baseUri: http://products.api.apievangelist.com
baseUri: http://mocksvc.mulesoft.com/mocks/a86239e0-d3af-48c6-9fd5-f8edc7c35d69
#List of media type to support
mediaType:  application/json
#List of protocols to support for baseUri
protocols: [ HTTP, HTTPS ]

#===============================================================
#  API documentation
#===============================================================
documentation:
  - title: Home
    content: | #This is a prototype product API.
  - title: Getting Started
    content: TODO   
                                  
#===============================================================
# API resource definitions
#===============================================================                        
          
/products:
  uriParameters:
  displayName: Products
  description: A collection of products
  post:
    description: Create a product
    #Post body media type support
    #text/xml: !!null  # media type text, xml support
    #application/json: !!null  #media type json support
    body:
      application/json:
        schema: |
          {
            "$schema": "http://json-schema.org/draft-03/schema",
            "product": {
                "name": {
                    "required": true,
                    "type": "string"
                },
                "description": {
                    "required": true,
                    "type": "string"
                },                
                "url": {
                    "required": true,
                    "type": "string"
                },                
                "image": {
                    "required": true,
                    "type": "string"
                },                
                "thumbnailUrl": {
                    "required": true,
                    "type": "string"
                },                
                "keywords": {
                    "required": true,
                    "type": "string"
                },                
                "brand": {
                    "required": false,
                    "type": "string"
                },                
                "color": {
                    "required": false,
                    "type": "string"
                },                
                "itemCondition": {
                    "required": false,
                    "type": "string"
                },                
                "manufacturer": {
                    "required": false,
                    "type": "string"
                },                
                "model": {
                    "required": false,
                    "type": "string"
                },                
                "sku": {
                    "required": false,
                    "type": "string"
                },                
                "weight": {
                    "required": false,
                    "type": "string"
                },                
                "width": {
                    "required": false,
                    "type": "string"
                },                
                "height": {
                    "required": false,
                    "type": "string"
                },                
                "depth": {
                    "required": false,
                    "type": "string"
                }
            },
            "required": true,
            "type": "object"
          }        
        example: |
          {
            "product": {
              "id": "1",
              "name": "Product One",
              "description": "This is the full description of the product.",
              "url": "http://example.com",
              "image": "http://example.com/image.jpg",
              "thumbnailUrl": "http://example.com/image-thumb.jpg",
              "keywords": "western, cowboy",
              "brand": "Brand Name",
              "color": "Black",
              "itemCondition": "New",
              "manufacturer": "Manufacturer Name",
              "model": "Black",
              "sku": "SKU #",
              "weight": "12 pounds",
              "width": "12 inches",
              "height": "12 inches",
              "depth": "12 inches"
            }
          }
  get:
    description: Get a list of products
    queryParameters:
      q:
        description: Search phrase to look for products
        type: string
        required: false
    responses:
      200:
        body:
          application/json: 
            #example: !include schema/product-list.json
                          
  #---------------------------------------------------------------
  # Nested resource representing a  single product - name parameter as part of the path.
  #---------------------------------------------------------------
  /{productId}: 
    description: | # Retrieve a specific product using its ID.
    uriParameters:
     productId:
       displayName: Product ID
       type: integer    
    get:
      description: Get a single product
      queryParameters:
        productId:
          description: The ID of the product
          type: integer
          required: true
      responses:
        200:
          body:
            application/json: 
              #example: !include schema/product-list.json
    put:
      description: Updates a single product
      queryParameters:
        productId:
          description: The ID of the product
          type: integer
          required: true
      body:
        application/json:
          schema: |
            {
              "$schema": "http://json-schema.org/draft-03/schema",
              "product": {
                  "name": {
                      "required": true,
                      "type": "string"
                  },
                  "description": {
                      "required": true,
                      "type": "string"
                  },                
                  "url": {
                      "required": true,
                      "type": "string"
                  },                
                  "image": {
                      "required": true,
                      "type": "string"
                  },                
                  "thumbnailUrl": {
                      "required": true,
                      "type": "string"
                  },                
                  "keywords": {
                      "required": true,
                      "type": "string"
                  },                
                  "brand": {
                      "required": false,
                      "type": "string"
                  },                
                  "color": {
                      "required": false,
                      "type": "string"
                  },                
                  "itemCondition": {
                      "required": false,
                      "type": "string"
                  },                
                  "manufacturer": {
                      "required": false,
                      "type": "string"
                  },                
                  "model": {
                      "required": false,
                      "type": "string"
                  },                
                  "sku": {
                      "required": false,
                      "type": "string"
                  },                
                  "weight": {
                      "required": false,
                      "type": "string"
                  },                
                  "width": {
                      "required": false,
                      "type": "string"
                  },                
                  "height": {
                      "required": false,
                      "type": "string"
                  },                
                  "depth": {
                      "required": false,
                      "type": "string"
                  }
              },
              "required": true,
              "type": "object"
            }        
          example: |
            {
              "product": {
                "id": "1",
                "name": "Product One",
                "description": "This is the full description of the product.",
                "url": "http://example.com",
                "image": "http://example.com/image.jpg",
                "thumbnailUrl": "http://example.com/image-thumb.jpg",
                "keywords": "western, cowboy",
                "brand": "Brand Name",
                "color": "Black",
                "itemCondition": "New",
                "manufacturer": "Manufacturer Name",
                "model": "Black",
                "sku": "SKU #",
                "weight": "12 pounds",
                "width": "12 inches",
                "height": "12 inches",
                "depth": "12 inches"
              }
            }          
      responses:
        200:
          body:
            application/json: 
              #example: !include schema/product-list.json  
    delete:
      description: Delete a single product
      queryParameters:
        productId:
          description: The ID of the product
          type: integer
          required: true
      responses:
        200:
          body:
            application/json: 
              #example: !include schema/product-list.json