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:

JSON elementDescriptionAlways Present
successBoolean with true=success, false=failureYes
payloadjson 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.No
messagePlain-text description of the resultNo
errorjson element with any error messages or warningsNo
idID of newly created object on POSTNo

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:

HTTP CodeMeaning
200OK
400Bad Request, method not supported by Buzz.
401Unauthorized, user doesn't have rights. See Accounts, Users, Roles, Permissions.
405Method not allowed by API. For example, some elements are read-only and cannot accept POST requests.
406Not acceptable, missing parameters or bad parameters. This is the most common error code when field validation fails for any reason.
409Conflict, 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 for more on strict mode.
429Rate 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 and Authentication endpoints.
500Internal server error, generally problem with the database or system setup.