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.
In order to create and update objects one needs to know their properties, required fields, and datatypes.
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.
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
"updateRequest.filters": string[ ]
The filters array indicates fields that can be updated on the object
"dataFlowPatchTypes": ""serviceType": ["create","update","delete"]"
A list of objects and the operations that can be used in a Data Flow.
"resourceRouting.routes": string[ ]
This array specifies all of the RESTful operations available.
"sqlMetadata.columns": column[ ]
The database properties for each column. Note isNullable and dataType properties.
"sqlMetadata.primaryKeys": string[ ]
Information about the primary key(s).
"sqlMetadata.foreignKeys": string[ ]
Information about any foreign keys.
"sqlMetadata.foreignKeyReferences": string[ ]
A list of tables that reference the table by primary key.
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.
Use this to indicate which page's data you wish
The number of results per page
The OutputFormat Headers allows your to specify the format of the response. The following formats are available:
The format field is mandatory for all output formats, however type and perEnvelope are only required for dataFlow output.
Indicates which the format
Only used for dataFlow. Possible values: create, update, and delete
Only used for dataFlow. The number of transactions per envelope
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.
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.