Data Payloads

This article explains how to format data for both requests and responses. In addition to the API documentation EngageIP has APIs and built in tools to assist you.

Request Data

In order to create and update objects one needs to know their properties, required fields, and datatypes.

API Documentation

The API documentation contains information about all the operations that can be done with each resource. Each objects's properties are listed with datatype, sample data, and indicate if the field is nullable.

Metadata APIs

Each resource has two Metadata APIs that will allow you GET knowledge about the resource. In fact the API documentation is created using them. We will be using the Metadata/sql Let's look at a sample from Service Type:

Let's look at some of the fields

Service Type Metadata sql
updateRequest.filters
"updateRequest.filters": string[ ]
Type: String
The filters array indicates fields that can be updated on the object
dataFlowPatchTypes
"dataFlowPatchTypes": ""serviceType": ["create","update","delete"]"
Type: String
A list of objects and the operations that can be used in a Data Flow.
resourceRouting.routes
"resourceRouting.routes": string[ ]
Type: String
This array specifies all of the RESTful operations available.
sqlMetadata.columns
"sqlMetadata.columns": column[ ]
Type: Column
The database properties for each column. Note isNullable and dataType properties.
sqlMetadata.primaryKeys
"sqlMetadata.primaryKeys": string[ ]
Type: String
Information about the primary key(s).
sqlMetadata.foreignKeys
"sqlMetadata.foreignKeys": string[ ]
Type: String
Information about any foreign keys.
sqlMetadata.foreignKeyReferences
"sqlMetadata.foreignKeyReferences": string[ ]
Type: String
A list of tables that reference the table by primary key.

Response Data

Paged APIs

Many times your response will include large amounts of data that you may wish to display using pagination. Each resource has a Paged template to simplify this process. You include the page details in the Pagination header.

Pagination Header
pageNumber
"pageNumber": 1
Type: Number
Use this to indicate which page's data you wish
pageSize
"pageSize": 20
Type: Number
The number of results per page

Output Format

The OutputFormat Headers allows your to specify the format of the response. The following formats are available:

  • dataFlow- Response is formatted in a format consumable by a Data Flow
  • instance- The default response format returns items in an array with all properties
  • result- Useful when submitting mutlitple transactions in a patch since this will itemize each transaction by result.

The format field is mandatory for all output formats, however type and perEnvelope are only required for dataFlow output.

Output Format Header
format
"format": "dataFlow"
Type: String
Indicates which the format
type
"type": "create"
Type: String
Only used for dataFlow. Possible values: create, update, and delete
perEnvelope
"perEnvelope": 20
Type: Number
Only used for dataFlow. The number of transactions per envelope

EngageIP Tools

Using Developer Tools

Developer tools for using APIs are available in the UI. Each resource is listed with operations organized by verb type. The Headers tab will allow you to see the relevant headers and edit them in the UI. If you are creating or updating an object the Body tab will list the properties in JSON format.

Using Logs

Since EngageIP is an API first platform, all operations are logged whether those operations are from the UI or an external application. When developing it can be useful to perfrom an operation in the UI and then look up the request body and headers in the Json API log. Navigate to Operations > Logs and find the request. The request tab will include the details of the request header and body.