{"_id":"56cf520b8629f91300fd97a9","githubsync":"","user":"56c39c05bc41330d009f25d7","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,"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,"project":"56c35c56c0c4630d004e864c","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-25T19:12:11.484Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","examples":{"codes":[]},"method":"put","auth":"required","params":[],"url":""},"isReference":true,"order":5,"body":"Updates use the `PUT` http method. In order to update an object you must pass the unique key of that object. For example, if you wish to update a `user`, the `user_id` field must be present in the JSON request along with whatever fields are meant to be updated.\n\nThe Buzz `PUT` method does not overwrite fields that are not present in the request, only those that are explicitly included. In some REST API implementations this behavior is handled by the `PATCH` verb, but this is not currently supported in Buzz.\n\nSome examples of both successful and unsuccessful PUT requests:\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"Example PUTs\"\n}\n[/block]\nSome examples of successful and unsuccessful PUT requests:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"new name\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nUNSUCCESSFUL: `advertiser_id` must be provided\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_id\\\":1, \\\"advertiser_name\\\":\\\"new name\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nSUCCESSFUL: `advertiser_id` 1 is updated with a new name\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_id\\\":[1,2,3], \\\"default_click_url\\\":\\\"http://www.foo.com\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nSUCCESSFUL: Advertisers 1, 2 and 3 are updated\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"Example PUT Requests\"\n}\n[/block]\nIn order to update an object you must use the object's unique ID. You can include this ID in the request path as shorthand, as shown in this example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"[host]/rest/user/1\\\" -b cookies.txt -d '{\\\"email\\\":\\\"new:::at:::email.com\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nWhich is equivalent to: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"[host]/rest/user\\\" -b cookies.txt -d '{\\\"user_id\\\":1, \\\"email\\\":\\\"new@email.com\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nWhen updating multiple objects, pass the IDs as a list:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X PUT \\\"[host]/rest/user\\\" -b cookies.txt -d '{\\\"user_id\\\":[1,2,3], \\\"email\\\":\\\"new@email.com\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"Multiple Object Updates\"\n}\n[/block]\nWhen updating multiple objects the http status and messaging will vary depending on whether all, none, or some of the objects were successfully updated as shown below:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Successful Updates\",\n    \"h-1\": \"HTTP status\",\n    \"h-2\": \"Message\",\n    \"0-0\": \"All\",\n    \"0-1\": \"200\",\n    \"0-2\": \"Success message\",\n    \"1-0\": \"Partial\",\n    \"1-1\": \"200\",\n    \"1-2\": \"WARNING message. The \\\"payload\\\" object will provide details on why some updates failed.\",\n    \"2-0\": \"None\",\n    \"2-1\": \"406 or other error code as appropriate\",\n    \"2-2\": \"ERROR message. The \\\"payload\\\" object will provide details on why updates failed.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nWhen using \"Strict mode\" the API will treat any errors as fatal and will not update any objects. This may be useful if your application wishes to avoid partial updates. Read more in [Using Extras for Fine-Tuning API Usage](doc:using-extras-for-fine-tuning-api-usage).","excerpt":"","slug":"put-ting-objects-with-the-api","type":"endpoint","title":"PUT-ting Objects with the API"}

putPUT-ting Objects with the API


Updates use the `PUT` http method. In order to update an object you must pass the unique key of that object. For example, if you wish to update a `user`, the `user_id` field must be present in the JSON request along with whatever fields are meant to be updated. The Buzz `PUT` method does not overwrite fields that are not present in the request, only those that are explicitly included. In some REST API implementations this behavior is handled by the `PATCH` verb, but this is not currently supported in Buzz. Some examples of both successful and unsuccessful PUT requests: [block:api-header] { "type": "put", "title": "Example PUTs" } [/block] Some examples of successful and unsuccessful PUT requests: [block:code] { "codes": [ { "code": "curl -X PUT \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"new name\"}'", "language": "curl" } ] } [/block] UNSUCCESSFUL: `advertiser_id` must be provided [block:code] { "codes": [ { "code": "curl -X PUT \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_id\":1, \"advertiser_name\":\"new name\"}'", "language": "curl" } ] } [/block] SUCCESSFUL: `advertiser_id` 1 is updated with a new name [block:code] { "codes": [ { "code": "curl -X PUT \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_id\":[1,2,3], \"default_click_url\":\"http://www.foo.com\"}'", "language": "curl" } ] } [/block] SUCCESSFUL: Advertisers 1, 2 and 3 are updated [block:api-header] { "type": "put", "title": "Example PUT Requests" } [/block] In order to update an object you must use the object's unique ID. You can include this ID in the request path as shorthand, as shown in this example: [block:code] { "codes": [ { "code": "curl -X PUT \"[host]/rest/user/1\" -b cookies.txt -d '{\"email\":\"new@email.com\"}'", "language": "curl" } ] } [/block] Which is equivalent to: [block:code] { "codes": [ { "code": "curl -X PUT \"[host]/rest/user\" -b cookies.txt -d '{\"user_id\":1, \"email\":\"new@email.com\"}'", "language": "curl" } ] } [/block] When updating multiple objects, pass the IDs as a list: [block:code] { "codes": [ { "code": "curl -X PUT \"[host]/rest/user\" -b cookies.txt -d '{\"user_id\":[1,2,3], \"email\":\"new@email.com\"}'", "language": "curl" } ] } [/block] [block:api-header] { "type": "put", "title": "Multiple Object Updates" } [/block] When updating multiple objects the http status and messaging will vary depending on whether all, none, or some of the objects were successfully updated as shown below: [block:parameters] { "data": { "h-0": "Successful Updates", "h-1": "HTTP status", "h-2": "Message", "0-0": "All", "0-1": "200", "0-2": "Success message", "1-0": "Partial", "1-1": "200", "1-2": "WARNING message. The \"payload\" object will provide details on why some updates failed.", "2-0": "None", "2-1": "406 or other error code as appropriate", "2-2": "ERROR message. The \"payload\" object will provide details on why updates failed." }, "cols": 3, "rows": 3 } [/block] When using "Strict mode" the API will treat any errors as fatal and will not update any objects. This may be useful if your application wishes to avoid partial updates. Read more in [Using Extras for Fine-Tuning API Usage](doc:using-extras-for-fine-tuning-api-usage).