{"_id":"56cf52d5287eb20b009f9f12","user":"56c39c05bc41330d009f25d7","category":{"_id":"56c35c57c0c4630d004e8650","version":"56c35c56c0c4630d004e864f","__v":17,"pages":["56c35c58c0c4630d004e8652","56c38f9c2d97560d00e23cb8","56c39b11e1e4190d003429b0","56c3a90c28bd680d005e7aa3","56c7b98a8bf67e0d0073477a","56c7b9d7379b311700ed8fe1","56c7bcc55652c217008e0923","56c7bee8606ee717003c4769","56cf423f8629f91300fd9779","56cf45b944c5700b0095c175","56cf4709287eb20b009f9eec","56cf49208acacb1300814884","56cf4c4c287eb20b009f9f01","56cf4d968629f91300fd9797","56cf4ede8acacb1300814890","56cf520b8629f91300fd97a9","56cf52d5287eb20b009f9f12"],"project":"56c35c56c0c4630d004e864c","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-02-16T17:28:55.483Z","from_sync":false,"order":0,"slug":"documentation","title":"Buzz API Overview"},"project":"56c35c56c0c4630d004e864c","version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"__v":2,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-25T19:15:33.106Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":9,"body":"The Buzz API supports path-based `extras` as well as the `options` parameter, each of which modify the behavior of the API. These are optional and can be used to debug or fine-tune your API usage. \n[block:api-header]\n{\n  \"title\": \"Extras\"\n}\n[/block]\nExtras change the behavior of the API in fundamental ways and are mutually exclusive (only one per API request). \n\nExtras are utilized by including the extra name in the path of the request as shown in the cURL example below where the `strict` extra is included:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser/strict\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"advertiser\\\", \\\"active\\\":1}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nSupported Extras and their behavior are shown below:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"extra\",\n    \"h-1\": \"executes API call?\",\n    \"h-2\": \"Functionality\",\n    \"0-0\": \"`fields`\",\n    \"0-1\": \"No\",\n    \"0-2\": \"Returns a JSON representation of the fields of the object being requested, along with whether the field is required or searchable.\",\n    \"1-0\": \"`help`\",\n    \"1-1\": \"No\",\n    \"1-2\": \"Returns custom help for the object. (Note, this is not widely implemented at this point)\",\n    \"2-0\": \"`strict`\",\n    \"2-1\": \"Yes\",\n    \"2-2\": \"Treats the JSON request strictly, throwing errors if there are extra, non-valid fields within the request and throwing a 409-Conflict error when any WARNINGs are incurred.\",\n    \"3-0\": \"`upload`\",\n    \"3-1\": \"Yes\",\n    \"3-2\": \"Allows for file uploads, when supported by the API object (usually Creative Assets)\",\n    \"4-0\": \"`validation`\",\n    \"4-1\": \"No\",\n    \"4-2\": \"Validates whether the request is valid but does not execute.\",\n    \"5-0\": \"`views`\",\n    \"5-1\": \"No\",\n    \"5-2\": \"Returns an array of available views for the object as well as the fields and metadata for that view. Useful for creating a UI on Buzz.\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Options\"\n}\n[/block]\nEvery API request to Buzz may include an extra parameter, `options` that modifies the response from the server. Options may be combined with each other, as well as with Extras.\n\nIn the example below we are using both the `time` and `compact` options. Options should be passed as a list, though for convenience when passing a single option a string is allowed.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser/strict\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"advertiser\\\", \\\"active\\\":1, \\\"options\\\":[\\\"time\\\",\\\"compact\\\"]}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"option\",\n    \"h-1\": \"result\",\n    \"0-0\": \"`time`\",\n    \"0-1\": \"Adds an extra field in the response showing the execution time of the request in milliseconds.\",\n    \"1-0\": \"`pretty`\",\n    \"1-1\": \"API response will be padded with whitespace to make it easier for human readability (opposite of `compact`).\",\n    \"2-0\": \"`compact`\",\n    \"2-1\": \"API response will have all whitespace removed to reduce filesize (opposite of `pretty`)\",\n    \"h-2\": \"notes\",\n    \"0-2\": \"Formerly the `time` parameter was an Extra, which is now deprecated.\",\n    \"1-2\": \"Based on your system setup, either `pretty` or `compact` may be your default. You can have this switched as required.\",\n    \"2-2\": \"Same as above.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]","excerpt":"","slug":"using-extras-for-fine-tuning-api-usage","type":"basic","title":"Using Extras for Fine-Tuning API Usage"}

Using Extras for Fine-Tuning API Usage


The Buzz API supports path-based `extras` as well as the `options` parameter, each of which modify the behavior of the API. These are optional and can be used to debug or fine-tune your API usage. [block:api-header] { "title": "Extras" } [/block] Extras change the behavior of the API in fundamental ways and are mutually exclusive (only one per API request). Extras are utilized by including the extra name in the path of the request as shown in the cURL example below where the `strict` extra is included: [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser/strict\" -b cookies.txt -d '{\"advertiser_name\":\"advertiser\", \"active\":1}'", "language": "curl" } ] } [/block] Supported Extras and their behavior are shown below: [block:parameters] { "data": { "h-0": "extra", "h-1": "executes API call?", "h-2": "Functionality", "0-0": "`fields`", "0-1": "No", "0-2": "Returns a JSON representation of the fields of the object being requested, along with whether the field is required or searchable.", "1-0": "`help`", "1-1": "No", "1-2": "Returns custom help for the object. (Note, this is not widely implemented at this point)", "2-0": "`strict`", "2-1": "Yes", "2-2": "Treats the JSON request strictly, throwing errors if there are extra, non-valid fields within the request and throwing a 409-Conflict error when any WARNINGs are incurred.", "3-0": "`upload`", "3-1": "Yes", "3-2": "Allows for file uploads, when supported by the API object (usually Creative Assets)", "4-0": "`validation`", "4-1": "No", "4-2": "Validates whether the request is valid but does not execute.", "5-0": "`views`", "5-1": "No", "5-2": "Returns an array of available views for the object as well as the fields and metadata for that view. Useful for creating a UI on Buzz." }, "cols": 3, "rows": 6 } [/block] [block:api-header] { "title": "Options" } [/block] Every API request to Buzz may include an extra parameter, `options` that modifies the response from the server. Options may be combined with each other, as well as with Extras. In the example below we are using both the `time` and `compact` options. Options should be passed as a list, though for convenience when passing a single option a string is allowed. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser/strict\" -b cookies.txt -d '{\"advertiser_name\":\"advertiser\", \"active\":1, \"options\":[\"time\",\"compact\"]}'", "language": "curl" } ] } [/block] [block:parameters] { "data": { "h-0": "option", "h-1": "result", "0-0": "`time`", "0-1": "Adds an extra field in the response showing the execution time of the request in milliseconds.", "1-0": "`pretty`", "1-1": "API response will be padded with whitespace to make it easier for human readability (opposite of `compact`).", "2-0": "`compact`", "2-1": "API response will have all whitespace removed to reduce filesize (opposite of `pretty`)", "h-2": "notes", "0-2": "Formerly the `time` parameter was an Extra, which is now deprecated.", "1-2": "Based on your system setup, either `pretty` or `compact` may be your default. You can have this switched as required.", "2-2": "Same as above." }, "cols": 3, "rows": 3 } [/block]