Platform API Introduction

Overview

The following API documentation for Improve Digital platform is available in the Help Centre:

This article contains general considerations related to the API design.

RESTful

A RESTful web service (also called a RESTful web API) is a web service implemented using HTTP and the principles of REST. It is a collection of resources, with the following defined aspects:

  • the Internet media type of the data supported by the web service. We support JSON.
  • the set of operations supported by the web service using HTTP methods (e.g., GET, PUT, POST, or DELETE).

 

Vocabulary re-use principle

 HTTP has a rich vocabulary of methods:

  • GET
  • POST
  • PUT
  • DELETE

The vocabulary re-use principle means that API will be designed in the way we need only two URLs and the CRUD operations can be achieved via different HTTP methods:

  • one for collections: /advertisers

  • one for element: /advertisers/[ID], where [ID] represents an identifier for the advertiser such as 555

 

Associations (owning)

Owning associations are those where parent entity owns the elements of the collection. The entities in the collection exist there. For instance: return contacts for the advertiser with the id [ID]

GET /advertisers/[ID]/contacts

Create contact for advertiser with id [ID]

POST /advertisers/[ID]/contacts

 

Associations (linked)

Linked associations are basically associations of links to real entities. The linked entities exist in another path. One such example are placements on a line item. Placements are maintained on the path /publisher/v1/publishers/{publisherId}/inventories/{inventoryId}/zones/{zoneId}/placements Line item has a number of assigned placements and they are accessible on the path: /publisher/v2/publishers/{publisherId}/campaigns/{campaignId}/line-items/{lineItemId}/placements

Links in that collection are obtained using GET method. Linking and unlinking is done via PUT method, where the entities in the collection submitted need only ID and assigned (true, false).

Link/unlink placements from Line Item

PUT /publisher/v2/publishers/{publisherId}/campaigns/{campaignId}/line-items/{lineItemId}/placements
Server: api.360yield.com
Content-Type: application/json
Accept: application/json

{
"placements": [
{
"id": 12345,
"assigned": true
},
{
"id": 13579,
"assigned": false
}
]
}

 

Filtering

Basic filtering can be done on the object properties for collection URLs:

GET /advertisers?status=active&name=joe

This call will return all active advertisers with the name joe. If the resulting object does not contain listed property, then the error will be returned.

 

Pagination

GET /advertisers?limit=25&offset=50

Where:

  • offset - the offset of first row to return (default offset value is 0)
  • limit - maximum numbers of the rows to return (default and max limit value is 100)

The pagination is applicable only for collection URLs.

In the response, the custom header x-360-content-range is set with the following info:

  • offset,
  • number of elements, and
  • total number of elements

in the form OFFSET | NUMBER_OF_ELEMENTS | TOTAL_NUMBER_OF_ELEMENTS.

Example

request
------------------------------
GET /advertisers?limit=25&offset=50

response header
------------------------------
x-360-content-range: 50|25|150

 

Sorting

Basic sorting can be done on the object property for collection URLs:

GET /advertisers?sort=-name

Sorting works as follows:

for given property name specified in sort query-string parameter, sort in ascending order, and
for property prefixed with a dash (“-”) sort in descending order.

 

Message Internationalization

In request header field Accept-Language is set desired message language.

Accept-Language: fr-CA

 

Versioning

Version number should be part of URL, for example:

/publisher/v1/advertisers
/auth/v1/token

Where version is v1, v2,... on the level of the service module, since some of the services will not change that often, so the versions will differ.

 

Restricting

In order to restrict the number of returned fields of an entity, we can use restrictions by passing fields parameter to restrict which data to return.

GET /advertisers?fields=id,name

Return error if listed field doesn't exists. Restrictions are possible on collections URLs only.

 

Format

The REST service should support JSON. The HTTP Content-Type and Accept headers will be used to specify (respectively) the format of the request (PUT/POST) and the format expected in the response (PUT/POST/GET/DELETE). The following value can be passed:

  • application/json

If no Accept header is passed, the JSON format will be assumed anyway.

 

Errors

The standard HTTP status codes should be used to notify client about the error, and besides that the JSON description of the error should be returned as well.
Limitations

API have three types of limitations:

  1. Resource (object) limitation
  2. Call limitation
  3. Paging limits

Resource limitation is maximum number of particular resource that can be created (eg. 1000 line items). All resource (inactive, archive...) states except deleted counts toward quota.

Call limitation is maximum number of reads and writes par minute. GET request is considered as read and POST, PUT and DELETE are considered as writes.

Paging limits are imposed on the number of entites clients can receive or submit to API services. The default, hard, limit is 100 entities per request.
Limitations

 

All limitations for logged publisher are available through the following API service:

Limitation API Service

Resource

POST

create

GET

read

PUT

update

DELETE

delete

/admin/v2/api-clients/default-call-limitations FORBIDDEN
Returns: HTTP 403
get default call limitations (API rate limits) applying to all API clients

Returns: HTTP 200 + JSON

Errors: HTTP 403,500 + description

FORBIDDEN
Returns: HTTP 403

FORBIDDEN
Returns: HTTP 403
/admin/v2/api-clients/[CLIENT_ID]/call-limitations

FORBIDDEN
Returns: HTTP 403

get call limitations (API rate limits) applying to a given API client

Returns: HTTP 200 + JSON

Errors: HTTP 403,500 + description

FORBIDDEN
Returns: HTTP 403

FORBIDDEN
Returns: HTTP 403

/admin/v2/publishers/default-resource-limitations

FORBIDDEN
Returns: HTTP 403

 

get default resource limitations applying to all publishers

Returns: HTTP 200 + JSON

Errors: HTTP 403,500 + description

FORBIDDEN
Returns: HTTP 403

FORBIDDEN
Returns: HTTP 403

 

/admin/v2/publishers/[PUBLISHER_ID]/resource-limitations

FORBIDDEN
Returns: HTTP 403

get resource limitations applying to a given publisher

Returns: HTTP 200 + JSON

Errors: HTTP 403,500 + description

FORBIDDEN
Returns: HTTP 403

FORBIDDEN
Returns: HTTP 403

 

Schemas are available on the following urls:

GET /schema/admin/v2/api-clients/default-call-limitations
GET /schema/admin/v2/api-clients/api-client/call-limitations
GET /schema/admin/v2/publishers/default-resource-limitations
GET /schema/admin/v2/publishers/publisher/resource-limitations

 

Access URL

The base URI for the production web services is https://api.360yield.com/

 

API for viewing the error schema

GET /schema/v1/error
Resource Role

POST
create

GET
read

PUT
update

DELETE
delete

/schema/v1/error Public

NOT ALLOWED

  • Returns: HTTP 405

retrieve error schema, XSD or JSON, according to the value in the accept HTTP header

  • Returns HTTP 200
  • Errors: HTTP 500 + description

NOT ALLOWED

  • Returns: HTTP 405

NOT ALLOWED

  • Returns: HTTP 405