{"_id":"56cf423f8629f91300fd9779","project":"56c35c56c0c4630d004e864c","__v":3,"githubsync":"","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"},"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"},"parentDoc":null,"user":"56c39c05bc41330d009f25d7","updates":["5b1e78ca92efb200034f9fbf"],"next":{"pages":[],"description":""},"createdAt":"2016-02-25T18:04:47.823Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":2,"body":"The Buzz API responds to every request with an http status indicating whether the request was successful, along with a json response. The json response includes:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"JSON element\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Always Present\",\n    \"0-0\": \"`success`\",\n    \"0-1\": \"Boolean with true=success, false=failure\",\n    \"0-2\": \"Yes\",\n    \"1-0\": \"`payload`\",\n    \"1-1\": \"json results of the request. For a GET request will include the results. For a POST or PUT will include the unique id of the object.\",\n    \"1-2\": \"No\",\n    \"2-0\": \"`message`\",\n    \"2-1\": \"Plain-text description of the result\",\n    \"2-2\": \"No\",\n    \"3-0\": \"`error`\",\n    \"3-1\": \"json element with any error messages or warnings\",\n    \"3-2\": \"No\",\n    \"4-0\": \"`id`\",\n    \"4-1\": \"ID of newly created object on POST\",\n    \"4-2\": \"No\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Success Element\"\n}\n[/block]\nThe first element of any API response will be the \"Success\" element, which will either be true or false. Example:\n```\"success\": true```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Successful GET Responses\"\n}\n[/block]\nWhen a GET request successfully executes, the second element in the response will be the `payload`, which will contain the data requested. Example of a successful GET:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"payload\\\": {\\n            \\\"user_id\\\": 1,\\n            \\\"first_name\\\":\\\"Danny\\\"\\n            ...\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Successful POST Responses\"\n}\n[/block]\nWhen a POST successfully executes, the `payload` element will be a success message, and an `id` element will be returned indicating the unique id of the object that was created. Example of a successful POST:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"payload\\\": \\\"user updated with ID 4\\\",\\n    \\\"id\\\": 4\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Successful PUT/DELETE Responses\"\n}\n[/block]\nWhen a DELETE or PUT request successfully executes, the \"payload\" element will be a list of messages and useful data for each affected object. Example of a successful POST:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"payload\\\": [\\n        {\\n            \\\"id\\\": 1,\\n            \\\"success\\\": false,\\n            \\\"error_code\\\": \\\"AD_BAD_VALIDATION\\\",\\n            \\\"message\\\": [\\n                \\\"ERROR: Error creating campaign_budget, field improperly formatted decimal\\\"\\n            ]\\n        },\\n        {\\n            \\\"id\\\": 30,\\n            \\\"success\\\": true,\\n            \\\"message\\\": \\\"campaign updated successfully\\\"\\n        }\\n        ],\\n        \\\"errors\\\": [\\n       \\\"ERROR: campaign update: 1 updated successfully, 1 with errors\\\"\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Unsuccessful Responses\"\n}\n[/block]\nUnsuccessful responses will aggregate all errors in the \"errors\" element, as shown in the example below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": false,\\n    \\\"payload\\\": \\\"Nothing found or problem with the query\\\",\\n    \\\"errors\\\": {\\n        \\\"ERROR: Nothing found matching those criteria\\\",\\n        \\\"WARNING: Something not so bad happened\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nNote, if the only error condition resulting from a request was a WARNING, the request will have `success=true`, but will also have a non-empty errors element.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP Codes\"\n}\n[/block]\nBuzz uses HTTP status codes to indicate whether a request was successful. If the response's HTTP code is 200, all worked well. The following codes represent other outcomes:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HTTP Code\",\n    \"h-1\": \"Meaning\",\n    \"0-0\": \"200\",\n    \"0-1\": \"OK\",\n    \"1-0\": \"400\",\n    \"1-1\": \"Bad Request, method not supported by Buzz.\",\n    \"2-0\": \"401\",\n    \"2-1\": \"Unauthorized, user doesn't have rights. See [Accounts, Users, Roles, Permissions](doc:accounts-users-roles-permissions).\",\n    \"3-0\": \"405\",\n    \"3-1\": \"Method not allowed by API. For example, some elements are read-only and cannot accept `POST` requests.\",\n    \"4-0\": \"406\",\n    \"4-1\": \"Not acceptable, missing parameters or bad parameters. This is the most common error code when field validation fails for any reason.\",\n    \"5-0\": \"409\",\n    \"5-1\": \"Conflict, thrown when an API request throws a `WARNING` and the request was made in strict mode. When not in \\\"strict\\\" mode a `WARNING` will return a 200. See: [Using Extras for Fine-Tuning API Usage](doc:using-extras-for-fine-tuning-api-usage) for more on strict mode.\",\n    \"7-0\": \"500\",\n    \"7-1\": \"Internal server error, generally problem with the database or system setup.\",\n    \"6-0\": \"429\",\n    \"6-1\": \"Rate limiting, thrown when an excessive number of requests are made in a short amount of time. Rate limiting is currently applied to the [Report Queue](doc:report-queue) and [Authentication](doc:authentication) endpoints.\"\n  },\n  \"cols\": 2,\n  \"rows\": 8\n}\n[/block]","excerpt":"","slug":"api-requests-and-responses","type":"basic","title":"API Requests and Responses"}

API Requests and Responses


The Buzz API responds to every request with an http status indicating whether the request was successful, along with a json response. The json response includes: [block:parameters] { "data": { "h-0": "JSON element", "h-1": "Description", "h-2": "Always Present", "0-0": "`success`", "0-1": "Boolean with true=success, false=failure", "0-2": "Yes", "1-0": "`payload`", "1-1": "json results of the request. For a GET request will include the results. For a POST or PUT will include the unique id of the object.", "1-2": "No", "2-0": "`message`", "2-1": "Plain-text description of the result", "2-2": "No", "3-0": "`error`", "3-1": "json element with any error messages or warnings", "3-2": "No", "4-0": "`id`", "4-1": "ID of newly created object on POST", "4-2": "No" }, "cols": 3, "rows": 5 } [/block] [block:api-header] { "type": "basic", "title": "Success Element" } [/block] The first element of any API response will be the "Success" element, which will either be true or false. Example: ```"success": true``` [block:api-header] { "type": "basic", "title": "Successful GET Responses" } [/block] When a GET request successfully executes, the second element in the response will be the `payload`, which will contain the data requested. Example of a successful GET: [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"payload\": {\n \"user_id\": 1,\n \"first_name\":\"Danny\"\n ...\n }\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Successful POST Responses" } [/block] When a POST successfully executes, the `payload` element will be a success message, and an `id` element will be returned indicating the unique id of the object that was created. Example of a successful POST: [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"payload\": \"user updated with ID 4\",\n \"id\": 4\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Successful PUT/DELETE Responses" } [/block] When a DELETE or PUT request successfully executes, the "payload" element will be a list of messages and useful data for each affected object. Example of a successful POST: [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"payload\": [\n {\n \"id\": 1,\n \"success\": false,\n \"error_code\": \"AD_BAD_VALIDATION\",\n \"message\": [\n \"ERROR: Error creating campaign_budget, field improperly formatted decimal\"\n ]\n },\n {\n \"id\": 30,\n \"success\": true,\n \"message\": \"campaign updated successfully\"\n }\n ],\n \"errors\": [\n \"ERROR: campaign update: 1 updated successfully, 1 with errors\"\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Unsuccessful Responses" } [/block] Unsuccessful responses will aggregate all errors in the "errors" element, as shown in the example below: [block:code] { "codes": [ { "code": "{\n \"success\": false,\n \"payload\": \"Nothing found or problem with the query\",\n \"errors\": {\n \"ERROR: Nothing found matching those criteria\",\n \"WARNING: Something not so bad happened\"\n }\n}", "language": "json" } ] } [/block] Note, if the only error condition resulting from a request was a WARNING, the request will have `success=true`, but will also have a non-empty errors element. [block:api-header] { "type": "basic", "title": "HTTP Codes" } [/block] Buzz uses HTTP status codes to indicate whether a request was successful. If the response's HTTP code is 200, all worked well. The following codes represent other outcomes: [block:parameters] { "data": { "h-0": "HTTP Code", "h-1": "Meaning", "0-0": "200", "0-1": "OK", "1-0": "400", "1-1": "Bad Request, method not supported by Buzz.", "2-0": "401", "2-1": "Unauthorized, user doesn't have rights. See [Accounts, Users, Roles, Permissions](doc:accounts-users-roles-permissions).", "3-0": "405", "3-1": "Method not allowed by API. For example, some elements are read-only and cannot accept `POST` requests.", "4-0": "406", "4-1": "Not acceptable, missing parameters or bad parameters. This is the most common error code when field validation fails for any reason.", "5-0": "409", "5-1": "Conflict, thrown when an API request throws a `WARNING` and the request was made in strict mode. When not in \"strict\" mode a `WARNING` will return a 200. See: [Using Extras for Fine-Tuning API Usage](doc:using-extras-for-fine-tuning-api-usage) for more on strict mode.", "7-0": "500", "7-1": "Internal server error, generally problem with the database or system setup.", "6-0": "429", "6-1": "Rate limiting, thrown when an excessive number of requests are made in a short amount of time. Rate limiting is currently applied to the [Report Queue](doc:report-queue) and [Authentication](doc:authentication) endpoints." }, "cols": 2, "rows": 8 } [/block]