The Adnuntius API is based on REST principles.
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 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 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.
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.
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"
}
}
Standard HTTP status codes are returned with each API response.
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
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.
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.
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.
Domain objects cannot be deleted, but they can be disabled or hidden by using the object’s Object State field.
When posting an object to the API for update, the following rules apply for fields:
All dates are represented as ISO 8601 strings in UTC timezone unless otherwise specified.
{
"time": "2015-01-01T01:00Z"
}
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_2API 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_1The 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 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.
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.
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 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 |
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 .