Overview
The following API documentation for Improve Digital platform is available in the Help Centre:
- API Introduction
- Client authentication
- Common Services / Common Schemas
- Publisher API Services
- Reporting API Service
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:
- Resource (object) limitation
- Call limitation
- 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 |
FORBIDDEN Returns: HTTP 403 |
| /admin/v2/api-clients/[CLIENT_ID]/call-limitations |
FORBIDDEN |
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 |
| /admin/v2/publishers/default-resource-limitations |
FORBIDDEN
|
get default resource limitations applying to all publishers Returns: HTTP 200 + JSON Errors: HTTP 403,500 + description |
FORBIDDEN Returns: HTTP 403 |
FORBIDDEN
|
| /admin/v2/publishers/[PUBLISHER_ID]/resource-limitations |
FORBIDDEN |
get resource limitations applying to a given publisher Returns: HTTP 200 + JSON Errors: HTTP 403,500 + description |
FORBIDDEN Returns: HTTP 403 |
FORBIDDEN
|
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 |
GET |
PUT |
DELETE |
| /schema/v1/error | Public |
NOT ALLOWED
|
retrieve error schema, XSD or JSON, according to the value in the accept HTTP header
|
NOT ALLOWED
|
NOT ALLOWED
|