The BidTheatre Developer Hub

Welcome to the BidTheatre developer hub. You'll find comprehensive guides and documentation to help you start working with BidTheatre as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Responses

Basics

When a request is successful, a response body will typically be sent back in the form of a JSON object.

🚧

An exception to this is when a DELETE request is processed, which will result in a successful HTTP 204 status and an empty response body.

Inside of this JSON object, the resource root that was the target of the request will be set as the key. This will be the singular form of the word if the request operated on a single object, and the plural form of the word if a collection was processed.

For example, if you send a GET request to

/v2.0/api/{network_id}/campaign/{id}

you will get back an object with a key called "campaign". However, if you send the GET request to the general collection at

/v2.0/api/{network_id}/campaign

you will get back an object with a key called "campaigns".

The value of these keys will generally be a JSON object for a request on a single object and an array of objects for a request on a collection of objects. When the response code if in the 400 and 500-range the key will be "error" and the object will contain additional information about the error.

Metadata

Some fields are returned in all responses regardless of what resource the request acted on and are there to provide details that could help troubleshooting. These field include

Field

Description

apiVersion

The version of the API the request was invoked on

code

The HTTP status code returned by the server. This is also located in the corresponding HTTP header field

method

The HTTP method the request invoked

networkId

The network the request was invoked on

Relationships

Fields in resources that contain 1-1 relationships with other resources will be displayed as "object links". That is a object that have two properties, href, that holds the absolute url to the resource, and the ID.

Fields in resources that contain 1-N relationships will be located as link objects in a links array. The link object contains two parameters, href and rel, where href is the absolute url to a resource collection and rel describes what kind of resource the collection contains. The collection url will in turn always return an array containing the relationship objects. To assign or remove this type of relationships issue DELETE or POST requests to the collection url, PUT is normally not allowed on these type of resources.

HTTP Response Status Codes

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes. These will both be accessible via the HTTP header as well as the code-field in the JSON response body.

In the event of a problem, the status will contain the error code, while the error-object of the response will usually contain additional information about the problem that was encountered.

Code

Description

200

GET- or PUT request was fulfilled successfully.

201

POST request was fulfilled successfully.

204

DELETE request was fulfilled successfully.

400

Bad input parameter. Error message should indicate which one and why.

401

Bad or expired token. Re-authenticate the user to resolve.

403

Invalid auth or the request attempts to access an unauthorized network.

404

Resource not found, issued for GET, DELETE and PUT requests when the resource wasn't found.

405

Request method not supported.

429

Too many requests. Your request have been throttled. See "Input and output throttling" below for more info.

500

Server side problem. Can be followed by an application error-code.

503

Service Unavailable. A needed sub-service is down causing this specific service to not function

Updated 2 years ago

Responses


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.