Infrastructure API

Document created by catherine.racette on Apr 13, 2017Last modified by catherine.racette on Jun 5, 2017
Version 6Show Document
  • View in full screen mode

Overview

Infrastructure APIs provide common functionality that is needed across multiple products; for example uploading entities in bulk, bulk downloads, etc.

 

Infrastructure API for bulk upload is essentially a delegating API, which does some groundwork and then delegates to an actual product specific API. The actual work is done by a more product specific API.

 

The Bulk Upload end points provided by the Infrastructure API are currently being used (via UI) for uploading publisher sites, publisher ad tags, channel partner domains, placements, F-cap and i-cap settings, publisher blocklist, channel partner domain deletion, campaign blocklist and whitelist etc.

 

The Bulk upload API operation itself is asynchronous (meaning you don't see results immediately). The following four APIs have been provided to upload and check status:

 

Methods

                                 

Method Path
HTTP Method Type
Description
Link to Definition
/infrastructure/bulkoperations
POST

This API gives the functionality of providing the bulk operations on APIs using supported multi-part request formats.

 

This method submits the file to the uploader process. (At this point processing has not completed.)

Bulk Uploads

/infrastructure/bulkOperations/GET

Get the list of bulk operations as per the criteria given in request.

 

This API can be used to check the status for a job that was submitted earlier.

Get all Bulk Uploads
/infrastructure/bulkOperations/{id}/failedRecordsGET

Once a job completes following APIs can be used to fetch records that went through and records which did not because of validation errors.

 

This method gets the file of failed records.

Get failed records
/infrastructure/bulkOperations/{id}/successfulRecordsGET

Once a job completes following APIs can be used to fetch records that went through and records which did not because of validation errors.

 

This method gets the file of successful records.

Get successful records

 

 

Bulk Uploads

Overview

End point for starting a bulk operation. After successful creation of a bulk operation, it will start processing the payload file asynchronously and will perform the actual API operations.

 

Once the basic file validations (empty file, file size, CSV header match) are done, the uploaded file is stored in the database and the Batch Id is generated for the same. This Batch Id can be used later to download successful and failed entries after the completion of entire process. Request is then sent to specific APIs to perform the operations as per input resource url.

Request

         
URI${uri_prefix}/infrastructure/bulkOperations
HTTP MethodPOST

Request Headers

                 

Header Name
Type
Value
Required
Description
Content-Typeapplication/jsonMust be MULTIPART_FORM_DATA
Yes

Request Query Parameters

                                                                                                                                                                                  

Body Parameter
Type
Required
Validations
Description
PubToken
String
Yes

${access_token}

Need to send the access token generating for authentication at the place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs

 

Sample Request

Bulk Domain Upload

http://localhost:8080/infrastructure/bulkOperations/[FileID]/successfulRecords?PubToken=xxxxx 

 

Response

Sample Response

The operation response with a CSV File. See attached example, "Sample_DomainsBulkUpload.csv.zip".

 

 

Get All Bulk Uploads

Overview

 

End point for retrieving all the upload details done for a publisher.

Request

         
URI${uri_prefix}/infrastructure/bulkOperations
HTTP MethodGET

Request Headers

                 

Header Name
Type
Value
Required
Description
Content-Typeapplication/json
Yes

Request Query Parameters

                                                                                                                                                                                  

Body Parameter
Type
Required
Validations
Description
PubToken
String
Yes

${access_token}

Need to send the access token generating for authentication at the place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs
entityId
Long
Yes

 

Publisher Id for which domains have been uploaded.
url
String
Yes
String to describe the type of bulk upload for which details have to be retrieved.
e.g., In case of domain upload value of uri will be "topLevelAd Container"
pageNumber
Integer
No
The starting count of records to be retrieved
pageSize
Integer
NoTotal number of records to be retrieved
sort
String
NoRetrieval order of the records

 

Sample Request

http://localhost:9090/infrastructure/bulkOperations?entityId=1234&PubToken=xxxxxxxxx&uri=topLevelAdContainer&dimensions=… 

Response

Sample Response JSON

{
   "metaData":{
      "startIndex":1,
      "totalRecords":1,
      "endIndex":10
   },
   "items":[
      {
         "id":123,
         "userId":123,
         "numberOfSuccessRecords":1,
         "numberOfErrorRecords":0,
         "fileName":"Uploaded_file.csv",
         "status":1,
         "creationTime":"2017-02-24 11:34:39",
         "comments":"",
         "bulkOperationsStatus":"Success",
         "userEmailId":"test@pubmatic.com",
         "modificationTime":"2017-02-24 11:35:43"
      }
   ]
}

 

Response Body

Parameter
Type
Description
metaDataObject
Contains meta information such as start index, end index and total records.
itemsList
Contains a list of bulk operation objects. The object contains file/batch id, user details (id ad email), number of successful and failed records, file name, bulk operation status (0=In Progress, 1=Success, 2=Failed) of the complete processing.

 

Get Failed Records

Overview

End point for retrieving all the failed records for input Batch/File Id. (This batch/file id is generated after the file is uploaded successfully during the bulk operation).

Request

         
URI${uri_prefix}/infrastructure/bulkOperations/{id}/failedRecords
HTTP MethodGET

Request Query Parameters

                                                                                                                                                                                  

Body Parameter
Type
Required
Validations
Description
PubToken
String
Yes

${access_token}

Need to send the access token generating for authentication at the place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs

 

Sample Request

 

http://localhost:8080/infrastructure/bulkOperations/23542/failedRecords?PubToken=xxxxx 

 

Response

Sample Response

The operation response with a file containing failed records in CSV format. See attached example, "FailedEntries.csv.zip".

 

Get Successful Records

Overview

End point for retrieving all the successful records for input Batch/File Id(This batch/file id is generated after the file is uploaded successfully during the bulk operation).

Request

         
URI${uri_prefix}/infrastructure/bulkOperations/{id}/successfulRecords
HTTP MethodGET

Request Query Parameters

                                                                                                                                                                                  

Body Parameter
Type
Required
Validations
Description
PubToken
String
Yes

${access_token}

Need to send the access token generating for authentication at the place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs

 

Sample Request

http://localhost:8080/infrastructure/bulkOperations/23542/successfulRecords?PubToken=xxxxx 

 

Response

Sample Response

The operation response with a file containing failed records in CSV format. See attached example, "SuccessfulEntries.csv.zip".

Outcomes