API Requests

Introduction

REST Principles

The Adnuntius API is based on REST principles.

GET

GET calls for many resources can be called with or without an object id in the url.

When the id is included then only that object will be returned.

GET http://<host>/api/v1/<resource type>/<id>

When no id is included then a list of all objects of that type visible to the user are returned.

GET http://<host>/api/v1/<resource type>

PUT AND POST

PUT and POST are both treated the same, they will both create an object if it does not exist, or update an object if it does.

When the id is included then only that object will be created/updated.

POST http://<host>/api/v1/<resource type>/<id>

When no id is included then a list of objects to be created/updated is expected as the request’s POST data.

POST http://<host>/api/v1/<resource type>

DELETE

DELETE is not supported on resources as domain objects cannot be deleted. See Object State and Deleting Data.

HEAD is used to confirm the existence of an object.

HEAD http://<host>/api/v1/<resource type>/<id>

The response code will be 200 OK if it exists or 404 NOT FOUND if it doesn’t.

Idempotence

The API supports the concept of idempotency and this means that the same PUT/POST call to an object can be made multiple times and only the initial call will alter the state of the object.

HATEOAS

The concept of HATEOAS is used to provide links between related objects.

For example, a Line Item links to many objects and both the related objects id and GET url is included.

{
"id": "lineitem_1",
"name": "Test Campaign",
"product": {
"id": "product_1",
"url": "http://test.api.com/api/v1/products/product_1"
}
}

Response codes

Standard HTTP status codes are returned with each API response.

API Conventions

Authorization

Access tokens

The Adnuntius API uses OAuth2 for authentication. In simplest terms, a user can request an access token from the API that can then be used to gain access to secured resources.

Token requests are made to the Authentication Resource.

Once an access token has been granted, it must be provided on every request to the API to access a secure resource. This is done by providing the token as the value for the Authorization: Bearer HTTP header

Versioning

The current version of the Adnuntius API is version 1 and is reflected in all API urls. There maybe changes to the API for a version, but there will never be breaking API changes so consumers can be confident that their code will continue to work against a version for the duration of its life time.

Transactionality

Each API call that modifies data results in a single transaction being committed against the data store. If multiple objects are being committed together and there is an error then no changes will be made.

Object State

All domain objects have an objectState field that can be set to one of the following enumeration values:

Object State

Description

ACTIVE

The object is active and visible

INACTIVE

The object is visible but not usable

HIDDEN

The object is neither visible or usable

Note that the API will return hidden objects if they are requested specifically by id, but it will not return them by default when requesting lists of objects. The includeHidden=true parameter can be used to include hidden objects.

Deleting Data

Domain objects cannot be deleted, but they can be disabled or hidden by using the object’s Object State field.

Updating fields

When posting an object to the API for update, the following rules apply for fields:

  • If a field is not included in the posted json then the field will not be modified.

  • If a field is included in the posted json then field will be updated.

  • Some fields can be set to null, but this depends on the object, the field and the field data type.

  • Collections are also replaced with the posted value. This also applies if an empty collection is sent - the existing collection will be replaced with the empty one.

Dates

All dates are represented as ISO 8601 strings in UTC timezone unless otherwise specified.

{
"time": "2015-01-01T01:00Z"
}

Vectorized Parameters

When requesting a list of objects, it is possible to pass a list of ids so only these objects are returned. Ids must be semicolon delimited.

GET http://<host>/api/v1/lineitems?context=<context>&id=lineitem_1;lineitem_2

Context Parameter

API requests for objects that belong to a network require a context parameter. The value is the id of the network that is the scope for the request.

GET http://<host>/api/v1/lineitems?context=network_1

API Responses

Validation Errors

The Adnuntius API is designed to be flexible and user friendly. Although validation on data being posted is kept to a minimum, some data may be rejected and the object will not be persisted. If the system rejects a value then a validation error will be returned explaining why. These validation errors are a type of translatable message.

Validation Warnings

Validation warnings are used to notify users that there is a problem with a persisted objects data. These warnings typically prevent the object from functioning, for example a Line Item with warnings will not be able to show ads. These validation warnings are a type of translatable message.

Paging

The system will page results for responses that contain an array of objects. Paged results will include:

Field

Description

page

The page number, 0 based

pageSize

The number of results per page

totalCount

The total number of objects

results

The array of objects

Note that page and pageSize can be passed as parameters to most resources. However in some cases all results are returned in a single page.

Error Responses

Along with the HTTP response codes, translatable messages are also returned to provide additional information.

ErrorMessages are returned for common error scenarios and ValidationErrorMessages are returned when an object update contains invalid data.

Translatable Messages

Translatable messages are used when the API returns a message that can be displayed to the end user.

All messages contains the following:

Field

Description

type

The type of message, see below

code

The unique code or key for this message

text

The English message that may contain param placeholders

params

A parameter name value map for placeholder substitution

Example:

{
"code": "error.referenced.object.not.found",
"text": "Referenced object {{type}} {{id}} not found",
"type": "ErrorMessage",
"params": [
"id": "lineitem_1",
"type": "Campaign"
]
}

Messages are used in a number of places within the system.

Message Type

Description

AuditMessage

Object Audit history messages from the audit resource

ErrorMessage

Error details returned when an error occurs

ForecastingMessage

Forecasting job progress messages

NotificationMessage

Notification/alert messages from the notification resource

ReportingMessage

Report execution status messages from the reports resource

ValidationErrorMessage

Data validation error details - changes were not persisted

ValidationWarningMessage

Data validation warning details - changes were persisted

Examples using cURL

This example uses cURL from a Linux terminal using jq for json parsing.

The examples use network_1 as the context.

While not suited for programmatic integration, this approach is simple and useful for testing and debugging.

Authentication This snippet authenticates and stores the access token as a shell variable so it can be used in subsequent API calls.

export ACCESS_TOKEN=$(curl -v -d grant_type=password -d scope=ng_api -d username=broker1@bitshift.technology -d password=broker1 "http://<host>/api/authenticate" | jq -r .access_token)

List Campaigns

curl -H "Authorization: Bearer $ACCESS_TOKEN" "http://<host>/api/v1/lineitems?context=network_1" | jq .

Get a Line Item

curl -H "Authorization: Bearer $ACCESS_TOKEN" "http://<host>/api/v1/lineitems/lineitem_1?context=network_1" | jq .

Create/update a Campaign

curl -H "Authorization: Bearer $ACCESS_TOKEN" -d @- -X PUT "http://<host>/api/v1/lineitems/lineitem_1?context=network_1" | jq .

This command will then accept json input from the command line.

Upload an Asset

Where leaderboard.png is the Asset file in the current directory that should be uploaded:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -F asset=@leaderboard.png "http://<host>/api/v1/assets/creative_1/asset_1?context=network_1" | jq .