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

FieldDescription
apiVersionThe version of the API the request was invoked on
codeThe HTTP status code returned by the server. This is also located in the corresponding HTTP header field
methodThe HTTP method the request invoked
networkIdThe 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.

CodeDescription
200GET- or PUT request was fulfilled successfully.
201POST request was fulfilled successfully.
204DELETE request was fulfilled successfully.
400Bad input parameter. Error message should indicate which one and why.
401Bad or expired token. Re-authenticate the user to resolve.
403Invalid auth or the request attempts to access an unauthorized network.
404Resource not found, issued for GET, DELETE and PUT requests when the resource wasn't found.
405Request method not supported.
429Too many requests. Your request have been throttled. See "Input and output throttling" below for more info.
500Server side problem. Can be followed by an application error-code.
503Service Unavailable. A needed sub-service is down causing this specific service to not function