{
  "name": "clickouts api",
  "apidoc": {
    "version": "0.11.52"
  },
  "description": "Host API documentation Click-Out Statistics API.",
  "base_url": "http://api.shopr.nl/stats",

  "info": {
    "contact": {
      "name": "Shopr Team"
    }
  },
  "enums": {
    "client_origin": {
      "description": "Describes the client where the request for a clickout has originated.",
      "values": [
        { "name": "shopr_website", "description": "The Shopr website" },
        { "name": "shopr_mobile_web", "description": "The Shopr website, but from a mobile." },
        { "name": "shopr_iphone", "description": "IPhone native application." },
        { "name": "shopr_ipad", "description": "Native application running on an IPad." },
        { "name": "shopr_android", "description": "Android native application." }
      ]
    }
  },
  "models": {
    "clickout": {
      "description": "Represents an Offer click-out. It contains all the information needed to properly identify the offer, trace it ot the user navigating from search page, and relevant information about the offer at the click-out moment (e.g.: price, lowest price among other offers, etc.)",
      "plural": "clickouts",
      "fields": [
        { "name": "productId", "type": "string", "description": "Product identifier", "example": "584f4c7f4cedfd0005e17c19" },
        { "name": "seller", "type": "string", "description": "Seller/Retailer unique identifier", "example": "klingel" },
        { "name": "sellerProductId", "type": "string", "description": "Product as identifier given by the seller/retailer", "example": "SAND003" },
        { "name": "price", "type": "decimal", "description": "Offer price at the moment of the click-out", "example": "67.00" },
        { "name": "deepUrl", "type": "string", "description": "Full product URL at the retailer side", "example": "http://www.klingel.nl/ProductDisplay?langId=31&catalogId=1000100000&storeId=100003&partNumber=460741&colorId=rood&attrId=G&vcp=gcqdjikm13m8iz&refID=Klingel_NL/Shopr/Dames/Schoenen/Pumps/Klassieke_pumps/04919/50X/&emsrc=Produktportale" },
        { "name": "lowestPrice", "type": "decimal", "description": "Lowest price among all offers", "example": "59.99" },
        { "name": "highestPrice", "type": "decimal", "description": "Seller/Retailer unique identifier", "example": "87.00" },
        { "name": "offerCount", "type": "integer", "minimum": 1, "description": "Number of offers", "default": 1, "example": "5" },
        { "name": "offerPosition", "type": "integer", "minimum": 1, "description": "Offer position among other offers (e.g.: first, second, etc.)", "example": "2" },
        { "name": "categoryId", "type": "string", "description": "Category where the product was put into", "example": "1234" },
        { "name": "tracking", "type": "tracking", "description": "Tracking information"},
        { "name": "creationTime", "type": "date-time-iso8601", "description": "When this click-out happened", "example": "2016-12-22T11:56:52Z" }
      ]
    },
    "tracking": {
      "description": "Series of attributes for tracking purposes",
      "fields": [
        { "name": "ipAddress", "type": "string" },
        { "name": "origin", "type": "client_origin", "description": "Client originating the order request essentially any of the values of the client_origin enum." },
        { "name": "userAgent", "type": "string", "required": false },
        { "name": "referrer", "type": "string", "required": false, "description": "Optional page referrer."}
      ]
    },
    "error_response": {
      "fields": [
        { "name": "message", "type": "string", "required": false, "description": "User-friendly message." },
        { "name": "error_codes", "type": "[error_code]", "description": "List of errors that may happened all together." },
        { "name": "fingerprint", "type": "string", "required": false, "description": "The request fingerprint associated with this error."}
      ]
    },
    "error_code": {
      "fields": [
        { "name": "code", "type": "string", "description": "Machine readable code for this specific error message", "example": "100" },
        { "name": "localized_string_code", "type": "string", "description": "A localized description of the error code", "example": "Lowest price cannot be bigger than highest price" }
      ]
    },
    "status": {
      "description": "Response for ping, health check and version",
      "fields": [
        { "name": "response", "type": "string", "example": "100ms | healthy | 0.0.1" }
      ]
    }
  },

  "resources": {
    "clickout": {
      "path": "/:fingerprint/clickouts",
      "operations": [
        {
          "method": "POST",
          "description": "Create a new click-out. Requests are accepted for eventual processing.",
          "parameters": [
            {
              "name": "fingerprint",
              "type": "string",
              "description": "User fingerprint used for correlation purposes.",
              "example": "cc7507cb65ffc750b298e722b34556c5"
            }
          ],
          "body": { "type": "clickout" },
          "responses": {
            "202": { "type": "string" },
            "422": { "type": "[error_response]", "description": "Example: lowestPrice is greater than highestPrice." }
          }
        }
      ]
    },
    "status": {
      "path": "/_internal_",
      "operations": [
        {
          "method": "GET",
          "path": "/ping",
          "description": "Ping in milliseconds.",
          "responses": {
            "200": { "type": "status" }
          }
        },
        {
          "method": "GET",
          "path": "/status",
          "description": "Current health check status.",
          "responses": {
            "200": { "type": "status"}
          }
        },
        {
          "method": "GET",
          "path": "/version",
          "description": "API version.",
          "responses": {
            "200": {"type": "string"}
          }
        }
      ]
    }
  }
}