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:

Success Element

The first element of any API response will be the "Success" element, which will either be true or false. Example:
"success": true

Successful GET Responses

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 ot the right:

{
    "success": true,
    "payload": {
            "user_id": 1,
            "first_name":"Danny"
            ...
    }
}

Successful POST Responses

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 to the right:

{
    "success": true,
    "payload": "user updated with ID 4",
    "id": 4
}

Successful PUT/DELETE Responses

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 to the right:

{
    "success": true,
    "payload": [
        {
            "id": 1,
            "success": false,
            "error_code": "AD_BAD_VALIDATION",
            "message": [
                "ERROR: Error creating campaign_budget, field improperly formatted decimal"
            ]
        },
        {
            "id": 30,
            "success": true,
            "message": "campaign updated successfully"
        }
        ],
        "errors": [
       "ERROR: campaign update: 1 updated successfully, 1 with errors"
    ]
}

Unsuccessful Responses

Unsuccessful responses will aggregate all errors in the "errors" element, as shown in the example to the right:

{
    "success": false,
    "payload": "Nothing found or problem with the query",
    "errors": {
        "ERROR: Nothing found matching those criteria",
        "WARNING: Something not so bad happened"
    }
}

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.

HTTP Codes

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: