API Requests

Learn how to make 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 https://api.adnuntius.com/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 https://api.adnuntius.com/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 https://api.adnuntius.com/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 https://api.adnuntius.com/api/v1/<resource type>

HEAD

HEAD is used to confirm the existence of an object.

HEAD https://api.adnuntius.com/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 Line Item",
    "order": {
        "id": "order_1",
        "url": "/api/v1/orders/order_1"
    }
}

Response codes

Standard HTTP status codes are returned with each API response.

API Conventions

Authorization

Access tokens

The Adnuntius API uses access tokens 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:

POST https://api.adnuntius.com/api/authenticate

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

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 https://api.adnuntius.com/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 https://api.adnuntius.com/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"
  ]
}

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=[e-mail] -d password=broker1 "https://api.adnuntius.com/api/authenticate" | jq -r .access_token)

List Line Items

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.adnuntius.com/api/v1/lineitems?context=network_1" | jq .

Get a Line Item

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.adnuntius.com/api/v1/lineitems/lineitem_1?context=network_1" | jq .

Create/update a Line Item

curl -H "Authorization: Bearer $ACCESS_TOKEN" -d @- -X PUT "https://api.adnuntius.com/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 "https://api.adnuntius.com/api/v1/assets/creative_1/asset_1?context=network_1" | jq .