{
  "endpoint": "AdHandler",
  "preferredHttpPath": "ad",
  "alternateHttpPaths": [
    "HttpAd"
  ],
  "summary": "In-house advertising-related APIs.",
  "description": "This endpoint contains all APIs related to in-house advertising.",
  "apis": [
    {
      "name": "PrepareInterstitialAdCredit",
      "httpMethod": "POST",
      "httpPathRegex": "^/prepare-credit",
      "subPathPattern": "/prepare-credit",
      "summary": "Prepares an interstitial ad credit for the specified user, allowing them to view an interstitial ad and given them a token that may be exchanged for a small amount of data transfer after a period of time.",
      "parameters": [
        {
          "name": "viewId",
          "required": true,
          "type": "String",
          "description": "A unique string that must be preserved and submitted with the returned token in order to receive credit."
        }
      ],
      "return": {
        "type": "PrepareInterstitialAdCreditResponse",
        "description": "A <see cref=\"T:PicMeApi.PrepareInterstitialAdCreditResponse\" /> containing the response."
      }
    },
    {
      "name": "RedeemInterstitialAdCredit",
      "httpMethod": "POST",
      "httpPathRegex": "^/redeem-credit",
      "subPathPattern": "/redeem-credit",
      "summary": "Prepares an interstitial ad credit for the specified user, allowing them to view an interstitial ad and given them a token that may be exchanged for a small amount of data transfer after a period of time.",
      "parameters": [
        {
          "name": "viewId",
          "required": true,
          "type": "String",
          "description": "A unique string that must be preserved and submitted with the returned token in order to receive credit."
        },
        {
          "name": "token",
          "required": true,
          "type": "String",
          "description": "The token that was returned by <see cref=\"M:PicMeApi.AdApis.PrepareInterstitialAdCredit(AmbientServices.IFileSystem,AmbientServices.AutoRotatingEncryptionKeyManager,PicMeApi.AuthData,System.String)\" />."
        }
      ],
      "return": {
        "type": "RedeemInterstitialAdCreditResponse",
        "description": "A <see cref=\"T:PicMeApi.RedeemInterstitialAdCreditResponse\" /> containing the response."
      }
    },
    {
      "name": "RecordImpression",
      "httpMethod": "POST",
      "httpPathRegex": "^/impression",
      "subPathPattern": "/impression",
      "summary": "Records an ad impression (an ad that was seen for a certain amount of time in a certain context by an end user).",
      "parameters": [
        {
          "name": "adId",
          "required": true,
          "type": "String",
          "description": "The identifier for the ad, as returned by <see cref=\"M:PicMeApi.AdApis.ListAds(AmbientServices.IFileSystem,AmbientServices.AutoRotatingEncryptionKeyManager,System.String,PicMeApi.AuthData,System.Boolean)\" />."
        },
        {
          "name": "collectionId",
          "required": false,
          "type": "String?",
          "description": "An optional collection ID to associate the ad serving with."
        },
        {
          "name": "contextId",
          "required": false,
          "type": "String?",
          "description": "A string identifying the context of the ad, ie. where on what place it is placed."
        }
      ],
      "return": {
        "type": "RecordImpressionResponse",
        "description": "A <see cref=\"T:PicMeApi.RecordImpressionResponse\" />."
      }
    },
    {
      "name": "ListAds",
      "httpMethod": "GET",
      "httpPathRegex": "^/ads",
      "subPathPattern": "/ads",
      "summary": "Lists possible ads to use for future ad impressions.",
      "parameters": [
        {
          "name": "collectionId",
          "required": false,
          "type": "String?",
          "description": "An optional collection ID to associate the ad serving with."
        },
        {
          "name": "unitTest",
          "required": false,
          "type": "Boolean",
          "description": "Whether or not this is a unit test."
        }
      ],
      "return": {
        "type": "ListAdsResponse",
        "description": "A <see cref=\"T:PicMeApi.ListAdsResponse\" /> containing the ads to display."
      }
    },
    {
      "name": "AdServe",
      "httpMethod": "GET",
      "httpPathRegex": "^/ad",
      "subPathPattern": "/ad",
      "status": "deprecated",
      "notes": "Use preloaded ads and impression recording instead",
      "summary": "Serves up an ad of the specified size.",
      "parameters": [
        {
          "name": "collectionId",
          "required": false,
          "type": "String?",
          "description": "An optional collection ID to associate the ad serving with."
        },
        {
          "name": "adSize",
          "required": false,
          "type": "AdSize?",
          "description": "An <see cref=\"T:PicMeApi.AdSize\" /> indicating what size ad to serve."
        },
        {
          "name": "contextId",
          "required": false,
          "type": "String?",
          "description": "A string identifying the context of the ad, ie. where on what place it is placed."
        },
        {
          "name": "unitTest",
          "required": false,
          "type": "Boolean",
          "description": "Whether or not this is a unit test."
        }
      ],
      "return": {
        "type": "RedirectResponse",
        "description": "Redirects directly to the ad image."
      }
    }
  ],
  "types": [
    {
      "name": "PrepareInterstitialAdCreditResponse",
      "summary": "A record containing the response from <see cref=\"M:PicMeApi.AdApis.PrepareInterstitialAdCredit(AmbientServices.IFileSystem,AmbientServices.AutoRotatingEncryptionKeyManager,PicMeApi.AuthData,System.String)\" />.",
      "type": "composite",
      "members": [
        {
          "name": "token",
          "type": "SignedSecurityToken",
          "summary": "The <see cref=\"T:AmbientServices.SignedSecurityToken\" /> assigned to the user and the specified view ID that will allow redemption of some kind of credit when the appropriate time has elapsed."
        }
      ]
    },
    {
      "name": "SignedSecurityToken",
      "summary": "A struct that holds a PicMe collection sharing authorization code.",
      "type": "proxy",
      "representedBy": "String"
    },
    {
      "name": "RedeemInterstitialAdCreditResponse",
      "summary": "A record containing the response from <see cref=\"M:PicMeApi.AdApis.RedeemInterstitialAdCredit(AmbientServices.IFileSystem,AmbientServices.AutoRotatingEncryptionKeyManager,PicMeApi.AuthData,System.String,System.String)\" />."
    },
    {
      "name": "RecordImpressionResponse",
      "summary": "A record containing the response from <see cref=\"M:PicMeApi.AdApis.RecordImpression(AmbientServices.IFileSystem,System.String,System.String,PicMeApi.AuthData,System.String)\" />."
    },
    {
      "name": "ListAdsResponse",
      "summary": "A list of ads to be displayed in the future.",
      "type": "composite",
      "members": [
        {
          "name": "ads",
          "type": "ListedAd[]",
          "summary": "An array of <see cref=\"T:PicMeApi.ListedAd\" /> objects, each containing information about one possible ad to display."
        }
      ]
    },
    {
      "name": "ListedAd",
      "summary": "An entry for the ad list.",
      "type": "composite",
      "members": [
        {
          "name": "size",
          "type": "AdSize",
          "summary": "The <see cref=\"T:PicMeApi.AdSize\" /> of this ad."
        },
        {
          "name": "adId",
          "type": "String",
          "summary": "The ID of the ad to display."
        },
        {
          "name": "uri",
          "type": "Uri",
          "summary": "A <see cref=\"P:PicMeApi.ListedAd.Uri\" /> for the image for the ad."
        },
        {
          "name": "expiration",
          "type": "DateTime",
          "summary": "A <see cref=\"T:System.DateTime\" /> indicating the UTC expiration of <paramref name=\"Uri\" />."
        }
      ]
    },
    {
      "name": "AdSize",
      "summary": "An enumeration of sizes for ads.",
      "type": "enum",
      "flags": false,
      "enumValues": [
        {
          "name": "Small",
          "summary": "A small ad, about 283x187 pixels.",
          "value": 0
        },
        {
          "name": "Medium",
          "summary": "A medium ad, about 283x343 pixels.",
          "value": 1
        },
        {
          "name": "Large",
          "summary": "A large ad.  ???x??? pixels.",
          "value": 2
        }
      ]
    },
    {
      "name": "RedirectResponse",
      "summary": "A special response type to use for an API that causes the framework code to respond with an HTTP redirect.  \n            This type and the properties within it are never actually returned to callers.\n            The caller will recieve a standard HTTP redirect response with a 30? redirect code and a \"Location\" header containing the location this API has redirected you to.\n            May also be thrown internally for conditional redirection.",
      "type": "proxy",
      "representedBy": "HttpRedirect"
    },
    {
      "name": "HttpRedirect",
      "summary": "An HTTP response containing a redirect HTTP status response code and a \"Location\" header with a new location for the resource.",
      "type": "composite",
      "members": [
        {
          "name": "location",
          "type": "Uri",
          "summary": "The new location."
        }
      ]
    }
  ]
}