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 element

Description

Always Present

success

Boolean with true=success, false=failure

Yes

payload

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.

No

message

Plain-text description of the result

No

error

json element with any error messages or warnings

No

id

ID of newly created object on POST

No

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 Code

Meaning

200

OK

400

Bad Request, method not supported by Buzz.

401

Unauthorized, user doesn't have rights. See Accounts, Users, Roles, Permissions.

405

Method not allowed by API. For example, some elements are read-only and cannot accept POST requests.

406

Not acceptable, missing parameters or bad parameters. This is the most common error code when field validation fails for any reason.

409

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 for more on strict mode.

429

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 and Authentication endpoints.

500

Internal server error, generally problem with the database or system setup.