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 StateDescription
ACTIVEThe object is active and visible
INACTIVEThe object is visible but not usable
HIDDENThe 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:

FieldDescription
pageThe page number, 0 based
pageSizeThe number of results per page
totalCountThe total number of objects
resultsThe 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:

FieldDescription
typeThe type of message, see below
codeThe unique code or key for this message
textThe English message that may contain param placeholders
paramsA 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 TypeDescription
AuditMessageObject Audit history messages from the audit resource
ErrorMessageError details returned when an error occurs
ForecastingMessageForecasting job progress messages
NotificationMessageNotification/alert messages from the notification resource
ReportingMessageReport execution status messages from the reports resource
ValidationErrorMessageData validation error details - changes were not persisted
ValidationWarningMessageData 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@adnuntius.com -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 .