Design Principles and Functionality of the OBP Rest API

Back to swagger

Contents

  1. General Remarks
  2. Access to the API
    1. Modifiability of JSON Fields
  3. HTTP Requests
    1. Common Functionality
    2. Cookies
    3. GET
      1. Wildcard Searches
    4. Post
    5. Put
    6. Patch
    7. Delete
      1. KeepMissingDetailsOnUpdate
    8. Header Parameters
    9. Path Parameters
  4. Versioning
  5. Database Data Model
  6. Powershell Examples
  7. Configuration
    1. Rules
      1. Matching Events
      2. Defining Actions
      3. Matching of item data
      4. Examples
  8. Glossary

1 General Remarks

2 Access to the API

The API is documented using Swagger. It provides this access point for development:https://int.audioxchange.de

The swagger page can be reached with this path:https://int.audioxchange.de/swagger/index.html

For each available version of the API, the complete definition is available.

Access to functions is always based on the pattern

/api/v{version}/{controller}/{function}{parameters}

As an example, to search for campaigns you can use something like:

api/v0.9/Campaign/FindCampaign?campaignId=4711

api/v0.9/Campaign/FindCampaign?wildcard=myCampaignName

api/v0.9/Campaign/FindCampaign?wildcard='%2B[tab;Campaign;col;Name;my campaign name]'

api/v0.9/Campaign/FindCampaign?wildcard='%3E[tab;Campaign;05.10.2020 09:37:39]' '%3C[tab;Campaign;05.10.2020 09:38:39]'&depthResult=0&maxRecords=100

The assignment of functions to the controllers is defined in the swagger description. Please note that the assignment is not identical to or derived from the swagger definition.

2.1 Modifiability of JSON fields

All relevant fields contained in the JSON objects accepted by the API can be classified into the following categories according to their accessibility:

Categories Description Display in Swagger
Required Fields marked as required must be defined in JSON and cannot be set to null. Required fields are indicated by red asterisk. For example:
Required
Optional These fields are not required and can be missing in JSON.
Attention: If a field is not available in JSON, then its database value will be overwritten with the default value of its data type.
Optional fields are not specially marked. For example:
Optional
Repeat Value on Update These should always be provided in the unchanged (= read out) state. Leave the fields empty on creation of object. The fields are decorated with the readonly: true annotation. For example:
RepeatValueOnUpdate
Computed The values are provided to the user. The fields are computed automatically and cannot be set via the API. Passing the values with JSON is optional - they are ignored.
The fields are marked analogous to the category "Repeat Value on Update". For example:
Computed
Wildcard Search This field type can be combined with any of the aforementioned field types.
These are annotated with the description Attribute is available for wildcard searches. For example:
Wildcard

3 HTTP Requests

3.1 Common Functionality

The API provides many functions which act similar. For each type of functions, the common behavior is outlined in this chapter to simplify understanding of the API. Nevertheless, some functions provide additional or different parameters.

The JSON returned is filtered for performance reasons to skip some of the data available. In general, the objects returned at the top level are complete, but detail objects may be truncated. In these cases, the detail objects can be queried directly to read the missing data. As an example, a request for a campaign might return details on people involved (planner, buyer, ...) but the details provided will include a name of the person but not all available fields.

3.2 Cookies

The OBP uses cookies for authentication. These cookies must be passed with every access. The only anonymous calls are

  • SignIn
  • SignInBody
  • SignIn2Fa

(Additional functions will follow for registration of new organizations)

3.3 GET

HTTP Get is used to query data. It returns either a single object or a list of objects.

Common Parameters   Description
Id Optional Id of the object. Restricts the results to only one object.
Wildcard Optional

Filters the data with a general filter. The data returned is always limited to the table queried. No details are returned.

This general search is performed whenever the id is not specified as search parameter.

DepthSearch Optional Depth of hierarchy to be searched for wildcard searches.
Example: when searching for a campaign, a level of
  • 0 will search in the Campaign
  • 1 will include CampaignElements and Files attached to the Campaign
  • 2 will include Plans and Files attached to a CampaignElement

Default value: 0 – search in the object itself only.

DepthResult Optional Depth of hierarchy to be returned.
Example: when searching for a campaign, a level of
  • 0 will return the Campaign
  • 1 will include CampaignElements and Files attached to the Campaign
  • 2 will include Plans and Files attached to a CampaignElement
When not searching for an id, the effect of this parameter depends on the number of records found and the context. If the result is unique, the requested depth is returned, otherwise the depth may be reduced automatically.

Default value: 0 – do not return details.

MaxRecords Optional

All requests returning a list of records provide a parameter to limit the number of rows returned by the top-level object.
This parameter always has a default value. The value depends on the context.

  • If a request returns less than maxRecords, all available records are returned.
  • In case exactly maxRecords are returned, it is unclear if more records exist. If it is important to see all records, repeat the query with a higher number of maxRecords.
  • If you want to display the first 10 records and an information, if further records exist, set maxRecords to 11 and show only 10 records.
SelectDetail Optional The result sets returned are filtered to optimize performance of the platform. In some cases, details on top-level are not included to speed up the queries. Parameter SelectDetail can be used to restrict query and result to one detail only (without subdetails). Parameter depthResult is ignored in this case, and depthSearch is implicitly set to 1.
Examples:
  • organization/findagency?depthresult=1&selectDetail=Advertisers
    will select all agencies available (in most cases, only one is visible) and include detail information on advertisers only.
  • campaign/findcampaign?id=80&depthresult=1&selectDetail=Buyer
    will return a campaign including the buyer of the campaign. Other details will be filtered out, e.g. CampaignElements.

Default value: null.

3.3.1 Wildcard Searches

Wildcard searches search in a defined depth, i.e. a range of database tables reached with a defined number of joins, on a predefined list of columns that are available for searches.

Wildcard searches support this syntax:
  • Spaces are token delimiters. To get a token with two words, use quotations. Valid quotations are ' and ". They cannot be escaped directly, but one of them can be used inside a pair of the others.
    • text
    • 'text1 text2'
    • 'text1 "textStartingWithDoubleQuotes'
  • Tokens are separated by space. All tokens are combined with 'and' unless 'or' is explicitly used as a token.
    • ' ' (space) -> and
    • ' or ' -> or
    • 'text1 text2' or text3
  • Tokens may be excluded: prepend token with -.
    • -text1
    • -'text1 text2'
  • Tokens (string) may be searched exactly: prepend token with + (%2B on URL). Note: -+ is available to exclude exact matches.
    • +text1
    • +'text1 text2'
  • Tokens (DateTime) may be compared: prepend token with > or < (on URL: %3E or %3C, respectively).
    • <23.09.2020
    • '>23.09.2020 10:12:13'
  • Brackets may be used to group tokens.
    • (a b) or (c d)
  • The search range for tokens can be restricted to tables or columns using square brackets. Inside the brackets, "tab" is used for table names, "col" is used for column names. These are valid search strings restricting the search to a tablename, a columnname, or both.
    Search expression Restriction Search text Remark
    Table Column
    [tab;tablename;col;columnname;searchtext] tablename columnname searchtext The search is restricted to table "tablename" and column "columnname".
    [tab;tablename;searchtext] tablename searchtext The search is restricted to table "tablename".
    [col;columnname;searchtext] columnname searchtext The search is restricted to column "columnname" in any table searched.
    [tab;Campaign;col;Name;campaign xxx] Campaign Name campaign xxx The search is restricted to exactly one column in one table.
    [col;Name;campaign xxx] Name campaign xxx The search is restricted to any table with a column named 'Name'.

3.4 Post

HTTP Post is used to create data. In most cases, the data is passed with the body parameter. When creating data, field Id must not be set and these fields are ignored:

  • LastChangeAccountId
  • LastChangeDate
  • RowVersion
  • KeepMissingDetailsOnUpdate

Some functions to create data allow detail data to be created immediately.

3.5 Put

HTTP Put is used to update data or to call functions.

A call to put may create detail data. As an example, you can

  • create a campaign (post)
  • search for a campaign (get)
  • update the campaign (put). This call to put may have added campaign elements to the body, which will be created automatically.

To distinguish between new detail objects and modified detail objects, the id of the detail object is used:

  • If an id is provided for the detail object, the object must exist on the database and it is checked for changes and stored.
  • If no id is provided for the detail object, a new object is created on the database.

To delete detail objects, the details are removed from the parent collection. This leads to a delete of the missing objects.

When an object is updated, it automatically updates its detail objects. These operations are performed:

  • If no id is provided for the detail object, a new object is created on the database.
  • If an id is provided for the detail object, the object must exist on the database and it is checked for changes and stored.
  • If a detail object is missing, the detail is removed from the database.

To keep a slim interface, an additional field “KeepMissingDetailsOnUpdate” exists on all classes. This field is not persisted. If it is set to true in an update operation, the check for missing details is skipped, allowing to pass only new or modified details to the server. For more details please refer to the subchapter 3.7.1 KeepMissingDetailsOnUpdate.

3.6 Patch

HTTP Patch is used to update partial resources. This is not supported by this API.

3.7 Delete

HTTP Delete is used to delete data. For this, the object itself is generally passed as the body parameter for verification of the row version. Depending on the data, this operation leads either to a delete on the database or the data as marked as no longer available.

For many objects, delete operations are performed using put-operations on the parent object.

3.7.1 KeepMissingDetailsOnUpdate

In order to delete non-desired child/subordinate entities from the database, do not provide them in a JSON passed in and set the value of the KeepMissingDetailsOnUpdate key to false while updating/modifying the corresponding parent entity. Once KeepMissingDetailsOnUpdate has been set, it will have the following impact on the delete behavior depending on the parent it has been applied for:

Parent Entity JSON Example Deletion Effects
Campaign Campaign JSON
  • OrgColumns

    All OrgColumns (except those provided in JSON, in our example: the one with Id "1") linked to Campaign with Id "1" will be deleted.

  • CampaignElements

    All CampaignElements linked to Campaign with Id "1" will be deleted, since none of them is referenced in JSON.

  • ObpFiles

    Analogous to CampaignElements.

CampaignElement CampaignElements JSON
  • OrgColumns

    All OrgColumns (except those provided in JSON, in our example: the one with Id "4") linked to campaignElement with Id "1" will be deleted.

  • Plans

    All Plans linked to CampaignElement with Id "1" will be deleted, since none of them is referenced in JSON.

  • ObpFiles

    Analogous to Plans.

<other tables> Analogous to the tables above.

3.8 Header Parameters

Parameter Value Category Description
Content-Type application/json Required, optional for requests without body parameter. This value must be set for all requests using body parameters.
OnBehalfOfOrganizationId 4711 Optional Work for another organization. Subagencies may work for the main agency, and platform administrators may work for any organization.
ContextInfo e.g. "MySignInTest" Optional, recommended A short information used to identify the calling context. This is copied to the log to simplify tracing problems.
X-Requested-With XMLHttpRequest Optional - tested only by users of API This value might help to avoid an automatic redirect on unsuccessful authentication, leading to an error code 401 instead of 302.

3.9 Path Parameters

Common Parameters   Description
Version Required

The version of the API used, e.g. “0.9”. The target is
  /api/v{version}/Person/…
or
  /api/v0.1/Person/…

4 Versioning

To simplify updates, the API is designed to provide multiple versions at the same time. All concurrently available versions target the same database. When a new API version is made available, older versions that can be kept active are mapped internally to the new version, e.g. by providing default values or by mapping values to new functionality. If an old version is kept active, it is marked as deprecated and will be disabled within a reasonable time frame.

There can be cases when old versions cannot be mapped automatically to new versions. In this case, the old versions will be set inactive with go live of the new version.

Active versions of the API are available in the Swagger documentation. For each API request, the version must be specified as a path parameter (see chapter 2, Access to the API, or 3.9, Path Parameters).

5 Database Data Model

The Rest API provides a JSON representation of the data. This representation does not fully mirror the data model used on the database server. Nevertheless, here is a shortened version of the data model on the database server:

database data model.

6 Powershell Examples

To use the examples, store all examples in one directory using the filename suggested.

To run an example, open powershell in the directory. Powershell version 7 or above is recommended.

Filename Usage Remark File Content
functions.ps1 . .\functions.ps1 Utilities used by other scripts
login.ps1 . .\login.ps1 Provide passwords in your copy of the file.

Run this once to store login information in the variables. Due to timeouts defined this needs to be repeated after longer idle time.
workflow1.ps1 . .\workflow1.ps1 A complete workflow script.

The 1st block of commands (before line 'ObpDocument "create a campaign"') depends on the agency / marketer used. Adapt wildcard searches to your needs/data.

Run .\ .login.ps1 first.

7 Configuration

7.1 Rules

The OBP creates events on creation or change of specific data items, e.g. when the state of a campaign changes. Based on these events special actions of the OBP can be configured by defining rules - either system wide or for a specific organization.

For a rule to be executed, this information/data is required:

  • An event definition.
  • An action to be executed.
When an event thrown matches the event definiton of a rule, the action defined in the rule is executed. In case event definitions of multiple rules match an event, every matching rule is executed.

Notes:

  • All configurations can be configured system-wide. System-wide configurations automatically apply to all organizations and cannot be switched off individually.
  • To remove a system-wide configuration for an organization, the configuration must be explicitly configured for all other organizations.
  • Organization-specific configurations can be added, e. g. to send additional emails.

7.1.1 Matching Events

Event definitions for rules contain this data:
  • A required name field to enable usage of the event definition within multiple rules.
  • Two required fields that must have exactly the value used in the event to be matched:
    • The event type.
    • The table id, i.e. the id of the data table on which the event occured.
  • Two optional attributes. These attributes can specify values the data item referenced in the event has before and after the event is thrown, e.g. the state of an object (old value and/or new value).

7.1.2 Defining Actions

These common actions are available:

Action Description Context Data Processing Data
Send a message Send an email and/or notification, depending on the user preferences. The data item triggering the event. Starting with this data item, parts of the item and data related to this item can be used in the messages. Details are described below. Parts of the message:
  • Mail to
  • Mail cc
  • Mail subject
  • Mail content
Update a worklist Reprocess a worklist for an item, i.e. update the worklist of all users to include or not include an item. The data item triggering the event. The worklist to update.
Actions include this data:
  • A required name field to enable usage of the action within multiple rules.
  • A required field specifying the action.
  • An optional attribute. This attribute can specify a data item reference for dynamic action data, e.g. to reference the actual state of an object. Please note that the actual state is the state availabe during rule processing, which might be updated after the event is thrown.

7.1.3 Matching of item data

To bind actions and event definitions to item data, attributes are used. They contain this data:
  • A required name field to enable usage of the attribute.
  • A required field 'TableName'. It may be empty.
  • A required field 'ColumnName'. It may be empty.
  • An optional field 'value'.
With the current implementatio, attributes are used for matching of rules to events only, i.e. comparing values in attributes of event definitons with values in data items.
  • Events contain (more precise, can contain depending on the event) values before and after event execution.
  • Event definitions may contain attributes for comparing the values before and after event execution.
  • 'TableName' and 'ColumnName' are not used for matching of event definitions.

Note: though actions can contain an attribute, this is not used with the current implementation. It is reserved for future usage.

To refer to item data within messages, there are two possibilities:

  1. Use the message content.
    Use square brackets within the content of the message. The text inside the square brackets is used to find the item data. These are the valid usages:

    Starting string Context Description
    Object:: Get property from object. Read a property value directly from an item data, e.g. [Object::Id] or [Object::BuyerId].
    Account:: Get Id of account for email / notifications. For message elements "mail to" and mail cc", an account id is required. To define elements sending mails to fixed accounts (not depending on item data), pass in [Account::<username>].
    ParameterNew:: Use event parameterNew. Directly insert the value provided in the event as "ValueNew" into the message. This is used to provide special data, e.g. an automatically created password, to an email.

  2. Use an empty message content, and provide columns TableName and ColumnName.
    In this case, the data table is navigated to from the item data of the event, using the "TableName". "TableName" may contain a hierachy of navigations. This hierarchy always starts with the table name of the item data. In the resulting table, property "ColumnName" is used.
    Example: to find the last name of the buyer of a campaign in a campaign-related event, use "TableName" = "Campaign.Buyer.Person" and "ColumnName" = "LastName".

7.1.4 Examples

This chapter presents a few possible rule definitions with their detail data.

Send a mail when a password is reset:
{
  "OrganizationId": 1,
  "Name": "AccountResetPassword",
  "EmDefinition": { "OrganizationId": 1, "Name": "AccountResetPassword", "EmEventType": "AccountResetPassword", "DbTableId": "Account" },
  "EmAction" : { "OrganizationId": 1, "Name": "SendMail", "ActionType": "SendMessage" },
  "Active" : true,
  "EmMessageElements": [
    { "OrganizationId": 1, "Name": "MailT_AccountResetPassword", "EmContentType": "MailTo" , "Content": "[Object::Id]" },
    { "OrganizationId": 1, "Name": "MailC_AccountResetPassword", "EmContentType": "MailContent", "Content": "Password: @[ParameterNew::]@" },
    { "OrganizationId": 1, "Name": "MailS_AccountResetPassword", "EmContentType": "MailSubject", "Content": "AccountResetPassword Username=@[Object::Username]@, Id=@[Object::Id]@." }
  ]
}

Notify platform admin after an organization is created:
{
  "Id": 19,
  "OrganizationId": 1,
  "Name": "CreateOrganizationNotify_OrgAdmin",
  "EmDefinition": { "OrganizationId": 1, "Name": "OrganizationChangeActiveState", "EmEventType": "OrganizationChangeActiveState", "DbTableId": "Organization" },
  "EmAction" : { "OrganizationId": 1, "Name": "SendMail", "ActionType": "SendMessage" },
  "Active" : false,
  "EmMessageElements": [
    { "OrganizationId": 1, "Name": "MailT_OrganizationCreate", "EmContentType": "MailTo" , "Content": "[Object::Id]" },
    { "OrganizationId": 1, "Name": "MailS_OrganizationCreate", "EmContentType": "MailSubject", "Content": "OrganizationChangeActiveState [Object::Name]@, Id=@[Object::Id]@, set to state @[ParameterNew::]@, state=@[Object::Active]@." },
  ]
}

8 Glossary

English German
Address Adresse
Advertiser Werbetreibender/Kunde
Agency Agentur
Booking plan Belegungsplan
Broadcasting company Rundfunkanstalt (Betreiber)
Broadcasting station,
Broadcaster
Radiosender
Campaign Kampagne
Campaign element Kampagnenelement
Channel Sender
Competition Konkurrenz
Contact Kontaktperson
Document Dokument
Gross Brutto
Marketer Vermarkter
Motif Motiv
Net Netto
Offer Angebot
Offer type Angebotsform (Produkt des Vermarkters)
Order Auftrag
Organization Unternehmen
Person Person
Plan Plan
Plan element Planelement
Product Produkt (des Werbetreibenden)
Reminder Reminder (Tandem, Tridem, Multispot)
Spot Schaltung, Termin, Werbespot
User Anwender
Period Zeitraum
Time schedule Terminplan
Variation plan Streuplan