Rest API
Introduction
REST stands for Representational State Transfer and is a style of software architecture that relies on stateless, client-server and cacheable communication protocols. HTTP is most commonly used and is the protocol that will be used for the REST API.
HTTP requests are used to post data (update and insert), retrieve data or search.
Incoming requests are by default queued (asynchronous request) until processing and process responses are returned to the same queue. Direct requests (synchronous) interrogate the database directly and are permitted less often. The document indicates clearly when this is the case. Some requests can even use streaming where results are already returned while the request is still processing.
When a request comes in a series of checks are made in the following order:
- Quota check
- Authentication verification
- IP filter check
The major benefits of REST technology are
- Scalability
- High volume
- Both Synchronous and asynchronous processing
- Language independent
Example of the structure a REST request:
http://[server]/phonebook/UserDetails/12345
This is an example of what a request might look like when retrieving the details of a specific user from a phonebook.
Example of an http path for direct request:
https://[server]/restapi/api/sync/..
Example of a path for queued request:
https://[server]/restapi/api/async/..
Dedicated API user
To be able to use the REST API a dedicated API user has to be created.
A name and login needs to be entered for the API user. The user's password is generated automatically and is used for hashing. The refresh button to the right of the field allows regenerating the password.
The API user must assign specific rights, indicating what operations can be performed through the API by that user and what operations can't.
API Functionality
Quota management
Quota management checks the number of incoming requests and blocks them when the quota for the respective client has been reached. At every new request that arrives the quota counter is decreased and returned. There are 3 possible quota settings, one for each type of request:
- Synchronous requests: This is a direct request and the result is returned immediately. The quota set for this type of request is stricter as it requires an immediate access to the database. This also means that for GET requests the cache is never consulted.
- Asynchronous requests:
- PUT/POST: Requests are queued and processed in the background. Status code 200/OK is returned immediately.
- GET: The cache is consulted first for a cached result, if unsuccessful the database will be queried.
- Stream requests: With this type of request answers are returned continuously while the request is being handled. There is no buffering of the response on the server.
For each request made, the remaining requests will be returned in the HTTP HEADER of the response.
- X-Quota-Sync
- X-Quota-Async
- X-Quota-Stream
Requests that fail the quota management check and that are not authenticated are not taken into account when calculating the quota. An HTTP error 403 is returned when the request is not within range.
Note: The quota is generally lower for direct(synchronous) requests as the database itself is interrogated. The default timespan of a quota is 5 minutes. After 5 minutes the quota counter is reset.
By default, all requests are configured with the following quota limits:
- Sync: 25 requests
- Async: 100 requests
- Stream: 1 request
- LifespanInSeconds: 300
Note: If needed, quota adjustments can be reviewed upon request by creating a ticket on our support portal.
Authentication
Every request must be authenticated. The authentication is based on the user name (readable), a hash code and a timestamp, all passed on through the Authorization HTTP header. The combination is preceded by 'hmac'
Example:
Authorization: hmac rdtest1:2AC5E7249082E2A76F6A0AD30DA37964D7522C8E1BBFD084705D52791D83EAA7:1372667542
- The user name corresponds to the API user created previously. The rights may be restricted in the Manager.
- The hash code is based on the HMAC-SHA-256 hashing method and comprises
- A timestamp: a UNIX timestamp, the same as used in the header
- The HTTP method: GET, POST, PUT.
- Relative path: the url where the request is made (example: http://someserver.com/restapi/api/sync/lists/1/profiles/1 )
- Request parameters: used to complete the request with parameters (example: http://someserver.com/restapi/api/sync/lists/1/profiles/1?fields=id,name)
Following is an example of a direct GET request where 2 fields (id, name) are retrieved from a profile with ID=1 in a userlist with ID=1:
1372667542-GET-/restapi/api/sync/lists/1/profiles/1?fields=id,name
- The time stamp is a UNIX timestamp. This MUST be the same timestamp used to generate the hash code.
- The key used to encode can be found in the API user properties in the Manager. (Check out section Dedicated API user)
When a request is received at the server, the user name in the request is used to retrieve information from the Marketing system. With this information the request parameters are rehashed using the client's password and compared with the hash in the authentication HTTP header. If this is the same, authentication succeeded.
The Timestamp is added both to the header and to the signature. Both are compared and must be equal for the request to be accepted. Additionally, a check is made to verify if the timestamp is within a specified interval of 5 minutes compared to the current server time.
Note: UTC times are used.
An HMAC can be used to determine whether a message sent over an insecure channel has been tampered with, provided that the sender and receiver share a secret key. The sender computes the hash value for the original data and sends both the original data and hash value as a single message. The receiver recalculates the hash value on the received message and checks that the computed HMAC matches the transmitted HMAC.
Any change to the data or the hash value results in a mismatch, because knowledge of the secret key is required to change the message and reproduce the correct hash value. Therefore, if the original and computed hash values match, the message is authenticated.
HMACSHA256 accepts keys of any size, and produces a hash sequence 256 bits in length.
IP filters
To filter requests and allow IP's to perform requests, the web.config file is edited. Only configured IPs are granted access.
A dedicated section <api> allows configuring these IP filters.
Some explanations:
- All IP filters are included in the <ipFilters> tag.
- The <ip> tag allows defining filters for a single IP, or a subnet using either the CIDR notation or providing a value for ‘mask’.
- The value for ‘address’ must be unique.
Paging
When requests return many results, it is handy to be able to perform paging on these results.
Note: Paging is not available for all requests but if it is it is by default active.
The mechanism works as follows:
When a result is returned, it contains the records of the current page and an indication of the total number of 'records' returned by the request. As the records are paged, the result contains links (url) indicating where the previous x records or next x records can be retrieved.
Example:
{
"result": [...],
"total": 999,
"_links": [{
"rel": "next"
"uri": "action-url?offset=401&size=200",
"verb": "GET"
} {
"rel": "prev",
"uri": "action-url?offset=201&size=200",
"verb": "GET"
}]
}- "result" contains the actual result.
- "_links" contains the path to the next or previous x records in the result.
- Offset indicates the start of the range. Size indicates the number of results in the page. The default is 200 and the maximum is 500.
The indicated URI must be added to the request URL after the “?”
Example:
1372667542-GET-/restapi/api/async/lists?offset=201&size=200
Functions
The key abstraction of information in REST is called a resource. Currently following resources are at hand:
- Profile: Represents a record from a user list, including 1:1 profile extensions.
- Lists: represents a user list
- Campaign: Represents a Marketing flow.
The operation to be executed is included in the HTTP header and can be one of the following:
- GET: Retrieve information
- PUT: Update a resource
- POST: Create new resource
Below you'll find an overview of the resources and methods allowed, with for each one an indication of the path to use, if direct requesting is supported, if streaming is allowed, if paging is possible. The default quota limits is provided as well.
Direct requests return a response. The url of direct requests contain the 'sync' element.
Some understanding on queued requests:
- The url of queued requests contain the 'async' element.
- Queued requests return a HTTP 200 (indicating the request has been accepted) and OK
Example:
Perform the following async request:
HTTP GET http://someserver.com/restapi/api/async/lists/1/profiles/91376
It will return the following response:
HTTP 200
Campaigns
Trigger (with campaign ID)
|
DESCRIPTION |
Use this method to enter data in an action list and trigger a campaign that sends an instant email with data from the action list. Note that the campaign must be designed to work with action lists and that a gate needs to be created as well. |
||||||||
|
Key |
Campaigns-Trigger |
||||||||
|
Path |
restapi/api/async/campaigns/{id}/trigger |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
No |
||||||||
|
Quota |
|
The following data needs to be passed on with the request:
- ActionList: contains the ID of the action list
- ActionListRecord: contains the data that needs to be put in the record
- Gate: The name of the gate used to access the campaign
- GateInput (optional): input parameters passed on to the gate
- User: The ID of the user for who the campaign is triggered
- UserListId: the ID of the user list to which the user belongs.
HTTP POST http://someserver.com/restap/api/async/campaigns/1378/trigger
{
"ActionList": 862,
"ActionListRecord": {
"ACTIONCODE": "TESTDATA",
"CONTENT": "[{\"ID\": 1,\"PARAM\":\"DATA\",\"CONTENT\":{\"CAPTION\":\"REST Api Test 3/07/2013 8:45:38\"}}]"
},
"Gate": "TRIGGERGATE",
"GateInput": null,
"User": 1,
"UserListId": 863
}HTTP 200 OK
Trigger (without campaign ID)
|
DESCRIPTION |
Use this method to enter data in an action list and trigger a campaign that sends an instant email with data from the action list. Note that the campaign must be designed to work with action lists and that a gate needs to be created as well. |
||||||||
|
Key |
Campaigns-Trigger |
||||||||
|
Path |
restapi/api/async/campaigns/trigger |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
No |
||||||||
|
Quota |
|
This trigger works the same as the one with a campaign ID (7.1.1). The only difference is that a gate is passed in the payload which refers to a campaign, so this implicitly identifies the campaign, and thus requires no campaign id.
The following data needs to be passed on with the request:
- ActionList: contains the ID of the action list
- ActionListRecord: contains the data that needs to be put in the record
- Gate: The name of the gate used to access the campaign
- GateInput (optional): input parameters passed on to the gate
- User: The ID of the user for who the campaign is triggered
- UserListId: the ID of the user list to which the user belongs.
HTTP POST http://someserver.com/restap/api/async/campaigns/trigger
{
"ActionList": 862,
"ActionListRecord": {
"ACTIONCODE": "TESTDATA",
"CONTENT": "[{\"ID\": 1,\"PARAM\":\"DATA\",\"CONTENT\":{\"CAPTION\":\"REST Api Test 3/07/2013 8:45:38\"}}]"
},
"Gate": "TRIGGERGATE",
"GateInput": null,
"User": 1,
"UserListId": 863
}HTTP 200 OK
TriggerbyJson
|
DESCRIPTION |
Use this method to trigger by Gate and optionally send parameters |
||||||||
|
Key |
CampaignAPITriggerByJson |
||||||||
|
Path |
restapi/api/sync/campaigns/triggerbyjson restapi/api/async/campaigns/triggerbyjson |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
No |
||||||||
|
Quota |
|
POST api/async/campaigns/triggerbyjson
Post body:
{
"Gate": "DBLX_GATE",
"GateInput": {
"PARAM1": "FIRST",
"PARAM2": "SECOND"
}
}HTTP 200 True
TriggerbyJsonWithResult
|
DESCRIPTION |
Use this method to trigger by Gate and optionally send parameters |
||||||||
|
Key |
CampaignAPITriggerByJsonWithResult |
||||||||
|
Path |
restapi/api/sync/campaigns/triggerbyjsonwithresult restapi/api/async/campaigns/triggerbyjsonwithresult |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
No |
||||||||
|
Quota |
|
POST api/async/campaigns/triggerbyjsonWithResult
Post body:
{
"Gate": "DBLX_GATE",
"GateInput": {
"PARAM1": "FIRST",
"PARAM2": "SECOND"
}
}// In case of success:
HTTP status 200
// and a JSON object like this:
{
"IsSuccess": true,
"Error": ""
}
// In case of failure:
HTTP status 400
// and a JSON object containing an error:
{
"IsSuccess": false,
"Error": "<some error string>"
}
Action Lists
Create One
|
DESCRIPTION |
Use this method to create data for one specific action list by providing the desired input. ListId, UserId and ActionCode are mandatory. CampaignId, ActionId and State are not allowed. Any other posted fields are arbitrary but are checked for existence against the action list table. |
||||||||
|
Key |
ActionList-Post |
||||||||
|
Path |
restapi/api/sync/lists/{id}/actions restapi/api/async/lists/{id}/actions |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/sync/lists/210/actions
{
"ActionId": "4",
"ListId": "171",
"UserId": "1",
"ActionCode": "unit test"
}HTTP 200 OK
{
"ActionId": "4",
"ListId": "171",
"UserId": "1",
"ActionCode": "unit test",
"CREATED_DT": "2013-08-21T09:02:03.0591404+02:00",
"Id": 10745041
}
Two extra fields, CREATED_DT and the assigned record ID, are added.
Create Many (streamed)
|
DESCRIPTION |
Use this method to create data for one or many action list entries by providing the desired input. ListId, UserId and ActionCode are mandatory. CampaignId, ActionId and State are not allowed. Any other posted fields are arbitrary but are checked for existence against the action list table. For this call it is required to provide the fields which will be posted on the first line, pipe-separated. |
||||||||
|
Key |
ActionList-Post-Stream |
||||||||
|
Path |
restapi/api/stream/lists/{id}/actions/post?mode={create/append} |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/stream/lists/210/actions/post?mode=append
ListId | UserId | ActionCode
{"ListId": "171", "UserId": "1", "ActionCode": "streaming unit test"}
{"ListId": "171", "UserId": "2", "ActionCode": "streaming unit test"}
{"ListId": "171", "UserId": "3", "ActionCode": "streaming unit test"}
…HTTP 200 OK
No additional content is returned.
Create action list
|
DESCRIPTION |
Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property. |
||||||||
|
Key |
Lists-Post |
||||||||
|
Path |
restapi/api/sync/lists restapi/api/async/lists |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
POST restapi/api/sync/lists
Post body:
{
"name": "ACTION_EXAMPLE_LIST",
"type": "ACTIONLIST",
"folder": 1964,
"owner": 279,
"disabled": 0,
"fields": [{
"column": "title",
"dataType": "text",
"maxLength": 50,
"required": true
}, {
"column": "description",
"dataType": "long text",
"maxLength": 50,
"required": false
}, {
"column": "act_int",
"dataType": "numeric",
"required": true
}, {
"column": "act_long",
"dataType": "long",
"required": false
}, {
"column": "act_float",
"dataType": "float",
"required": true
}, {
"column": "act_datetime",
"dataType": "datetime",
"required": true
}, {
"column": "act_date",
"dataType": "date",
"required": true
}, {
"column": "act_boolean",
"dataType": "boolean",
"required": false
}]
}HTTP 200 OK
{
"id": 4248,
"type": "ACTIONLIST",
"tablename": "DB_DEVU_DATA.dbo.ACTION_ACTION_EXAMPLE_LIST",
"name": "ACTION_EXAMPLE_LIST",
"description": null,
"folder": 1964,
"owner": 279,
"disabled": null,
"fields": [{
"column": "ID",
"primary_key": true,
"required": true,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
}, {
"column": "CREATED_DT",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Datetime"
}, {
"column": "MODIFIED_DT",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Datetime"
}, {
"column": "EXEC_DT",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Datetime"
}, {
"column": "CAMPAIGNID",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
}, {
"column": "ACTIONID",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
}, {
"column": "LISTID",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
}, {
"column": "USERID",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
}, {
"column": "STATE",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
}, {
"column": "ACTIONCODE",
"primary_key": false,
"required": false,
"maxlength": 50,
"optionlist": 0,
"datatype": "Text"
}, {
"column": "title",
"primary_key": false,
"required": true,
"maxlength": 50,
"optionlist": 0,
"datatype": "Text"
},
{
"column": "description",
"primary_key": false,
"required": false,
"maxlength": 50,
"optionlist": 0,
"datatype": "Long Text"
}, {
"column": "act_int",
"primary_key": false,
"required": true,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
}, {
"column": "act_long",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Long"
}, {
"column": "act_float",
"primary_key": false,
"required": true,
"maxlength": 0,
"optionlist": 0,
"datatype": "Float"
}, {
"column": "act_datetime",
"primary_key": false,
"required": true,
"maxlength": 0,
"optionlist": 0,
"datatype": "Datetime"
}, {
"column": "act_date",
"primary_key": false,
"required": true,
"maxlength": 0,
"optionlist": 0,
"datatype": "Date"
}, {
"column": "act_boolean",
"primary_key": false,
"required": false,
"maxlength": 0,
"optionlist": 0,
"datatype": "Boolean"
}
],
"_links": [{
"rel": "self",
"uri": "api/async/lists/4248",
"verb": "GET"
}, {
"rel": "self",
"uri": "api/async/lists/4248",
"verb": "PUT"
}]
}
Lists
Create One
|
DESCRIPTION |
Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property. All listed fields in the example are mandatory. |
||||||||
|
Key |
Lists-Post |
||||||||
|
Path |
restapi/api/sync/lists restapi/api/async/lists |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/sync/lists
{
"type": "USERLIST",
"tablename": "USERS_DEMO_MATRIX",
"name": "DEMO_MATRIX - MASTER LIST",
"folder": "1",
"owner": "9",
"disabled": "0",
"fields": [{
"column": "street",
"dataType": "text",
"maxLength": 50,
"required": false
}, {
"column": "areacode",
"dataType": "numeric",
"required": false,
"optionlist": 23
}]
}HTTP 200 OK
{
"id": "1",
"type": "USERLIST",
"tablename": "USERS_DEMO_MATRIX",
"name": "DEMO_MATRIX - MASTER LIST",
"folder": "1",
"owner": "9",
"disabled": "0",
"fields": [{
"column": "street",
"dataType": "text",
"maxLength": 50,
"required": false
}, {
"column": "areacode",
"dataType": "numeric",
"required": false,
"optionlist": 23
}],
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "PUT"
}, {
"rel": "schema",
"uri": "restapi/api/sync/lists/1/schema",
"verb": "GET"
}, {
"rel": "relations",
"uri": "restapi/api/sync/lists/1/relations",
"verb": "GET"
}, {
"rel": "search",
"uri": "restapi/api/sync/lists/1/profiles/search",
"verb": "POST"
}, {
"rel": "profiles",
"uri": "restapi/api/sync/lists/1/profiles",
"verb": "GET"
}]
}
The result returns
- The list ID
- Type
- Tablename
- Name
- Folder
- Owner
- Disabled
- The _links section provides insight in all other actions that can be performed on the list.
Read One
|
DESCRIPTION |
Use this method to retrieve the metadata for one specific list by using the ID of the list. |
||||||||
|
Key |
ActionList-Get |
||||||||
|
Path |
restapi/api/sync/lists/{id}/actions restapi/api/async/lists/{id}/actions |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the URL path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP 200 OK
{
"id": "1",
"type": "USERLIST",
"tablename": "USERS_DEMO_MATRIX",
"name": "DEMO_MATRIX - MASTER LIST",
"folder": "1",
"owner": "9",
"disabled": "0",
"fields": [{
"column": "street",
"dataType": "text",
"maxLength": 50,
"required": false
}, {
"column": "areacode",
"dataType": "numeric",
"required": false,
"optionlist": 23
}],
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "PUT"
}, {
"rel": "schema",
"uri": "restapi/api/stream/lists/1/schema",
"verb": "GET"
}, {
"rel": "relations",
"uri": "restapi/api/stream/lists/1/relations",
"verb": "GET"
}, {
"rel": "search",
"uri": "restapi/api/stream/lists/1/profiles/search",
"verb": "POST"
}, {
"rel": "profiles",
"uri": "restapi/api/stream/lists/1/profiles",
"verb": "GET"
}]
}The result returns
- The list ID
- Type
- Tablename
- Name
- Folder
- Owner
- Disabled
- The _links section provides insight in all other actions that can be performed on the list.
Read All (paged)
|
DESCRIPTION |
Use this method to retrieve the metadata for all lists the user has access to |
||||||||
|
Key |
ActionList-Get |
||||||||
|
Path |
/restapi/api/sync/lists /restapi/api/async/lists |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
Yes |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP 200 OK
{
"result": [{
"id": "1",
"type": "USERLIST",
"tablename": "USERS_DEMO_MATRIX",
"name": "DEMO_MATRIX - MASTER LIST",
"folder": "1",
"owner": "9",
"disabled": "0",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "PUT"
}, {
"rel": "schema",
"uri": "restapi/api/sync/lists/1/schema",
"verb": "GET"
}, {
"rel": "relations",
"uri": "restapi/api/sync/lists/1/relations",
"verb": "GET"
}, {
"rel": "search",
"uri": "restapi/api/sync/lists/1/profiles/search",
"verb": "POST"
}, {
"rel": "profiles",
"uri": "restapi/api/sync/lists/1/profiles",
"verb": "GET"
}]
}, ...],
"total": 635,
"_links": [{
"rel": "next",
"uri": "restapi/api/sync/lists/?offset=201&size=200",
"verb": "GET"
}]
}For each list information is returned on
- The list ID
- Type
- Tablename
- Name
- Folder
- Owner
- Disabled
- The _links section provides an overview of all other actions that can be performed on the resource. The uri to be able to perform the action is provided as well.
Read All (streamed)
|
DESCRIPTION |
Use this method to retrieve the metadata for all lists the user has access to and this using the stream method. |
||||||||
|
Key |
Lists-Get-Stream |
||||||||
|
Path |
/restapi/api/stream/lists |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
HTTP 200 OK
First result:
{
"id": "1",
"type": "USERLIST",
"tablename": "USERS_DEMO_MATRIX",
"name": "DEMO_MATRIX - MASTER LIST",
"folder": "1",
"owner": "9",
"disabled": "0",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "PUT"
}, {
"rel": "schema",
"uri": "restapi/api/stream/lists/1/schema",
"verb": "GET"
}, {
"rel": "relations",
"uri": "restapi/api/stream/lists/1/relations",
"verb": "GET"
}, {
"rel": "search",
"uri": "restapi/api/stream/lists/1/profiles/search",
"verb": "POST"
}, {
"rel": "profiles",
"uri": "restapi/api/stream/lists/1/profiles",
"verb": "GET"
}]
}
Second result:
{
"id": "3",
"type": "ACTIONLIST",
"tablename": "ACTION_EXT_ACTIONS",
"name": "EXT_ACTIONS",
"folder": "5",
"owner": "18",
"disabled": "null",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/3",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/3",
"verb": "PUT"
}, {
"rel": "schema",
"uri": "restapi/api/stream/lists/3/schema",
"verb": "GET"
}, {
"rel": "relations",
"uri": "restapi/api/stream/lists/3/relations",
"verb": "GET"
}, {
"rel": "search",
"uri": "restapi/api/stream/lists/3/profiles/search",
"verb": "POST"
}, {
"rel": "profiles",
"uri": "restapi/api/stream/lists/3/profiles",
"verb": "GET"
}]
}
…For each list information is returned on
- The list ID
- Type
- Tablename
- Name
- Folder
- Owner
- Disabled
- The _links section provides an overview of all other actions that can be performed on the resource. The uri to be able to perform the action is provided as well.
Modify One
|
DESCRIPTION |
Use this method to modify the metadata for one specific list by using the ID of the list and the desired data to modify. Fields with no change must be supplied with value ‘null’. 'type' is mandatory. |
||||||||
|
Key |
Lists-Put |
||||||||
|
Path |
/restapi/api/sync/lists/{id} /restapi/api/async/lists/{id} |
||||||||
|
Method |
PUT |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP PUT http://someserver.com/restapi/api/sync/lists/1
{
"id": "1",
"type": null,
"tablename": null,
"name": "Table Caption Changed",
"folder": null,
"owner": null,
"disabled": null
}HTTP 200 OK
{
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1",
"verb": "PUT"
}, {
"rel": "schema",
"uri": "restapi/api/sync/lists/1/schema",
"verb": "GET"
}, {
"rel": "relations",
"uri": "restapi/api/sync/lists/1/relations",
"verb": "GET"
}, {
"rel": "search",
"uri": "restapi/api/sync/lists/1/profiles/search",
"verb": "POST"
}, {
"rel": "profiles",
"uri": "restapi/api/sync/lists/1/profiles",
"verb": "GET"
}]
}The result returns
- The list ID
- Type
- Tablename
- Name
- Folder
- Owner
- Disabled
- The _links section provides insight in all other actions that can be performed on the list.
Get searchable fields
|
DESCRIPTION |
Use this method to retrieve a list of fields that are indexed for search purposes. |
||||||||
|
Key |
Lists-Get-SearchFields |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/searchfields |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP GET http://someserver.com/restapi/api/sync/lists/1845/searchfieldsHTTP 200 OK
[{
"column": "ID",
"primary_key": true,
"required": true,
"maxlength": -1,
"optionlist": 0,
"datatype": "Numeric",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1845/fields/id",
"verb": "PUT"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1845/fields/id",
"verb": "DELETE"
}]
}, {
"column": "NAME",
"primary_key": false,
"required": false,
"maxlength": 50,
"optionlist": 0,
"datatype": "Text",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1845/fields/name",
"verb": "PUT"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1845/fields/name",
"verb": "DELETE"
}]
}]
Lists Profiles
Create One
|
DESCRIPTION |
Use this method to create a new user record in a specific user list. It is possible to insert data in 1:1 profile extensions as well. |
||||||||
|
Key |
Profiles-Post |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/profiles /restapi/api/async/lists/{id}/profiles |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/sync/lists/863/profiles
{
"Name": "Test user",
"Mail": "testuser-restapi@selligent.be",
"MyField": "test dynamic field",
"ActionTriggerlink.Created_dt": "2013-07-03T10:09:01.4440802+02:00",
"ActionTriggerlink.CampaignId": 1376,
"ActionTriggerlink.ActionId": 2,
"ActionTriggerlink.ListId": 863,
"ActionTriggerlink.UserId": 1,
"ActionTriggerlink.State": 30,
"ActionTriggerlink.ActionCode": "RestApiTest-3/07/2013 10:09:01",
"Extensions.TwitterHandle": "suddenelfilio",
"Domains.MailDomain": "selligent.be"
}In the above example 'ActionTriggerLink', 'Extensions' and 'Domains' are profile extensions of the userlist with id=863.
Note that the fields passed on to the request differ from one userlist to another and should be adapted accordingly.
HTTP 200 OK
{
"Name": "Test user",
"Mail": "testuser-restapi@selligent.be",
"MyField": "test dynamic field",
"ActionTriggerlink.Created_dt": "2013-07-03T10:09:02.7921573+02:00",
"ActionTriggerlink.CampaignId": 1376,
"ActionTriggerlink.ActionId": 2,
"ActionTriggerlink.ListId": 863,
"ActionTriggerlink.UserId": 119,
"ActionTriggerlink.State": 30,
"ActionTriggerlink.ActionCode": "RestApiTest-3/07/2013 10:09:01",
"ActionTriggerlink.Id": 145,
"Extensions.TwitterHandle": "suddenelfilio",
"Extensions.Id": 72,
"Domains.MailDomain": "selligent.be",
"Domains.MAIL": "testuser-restapi@selligent.be",
"Domains.Id": 64,
"CREATED_DT": "2013-07-03T10:09:02.7701561+02:00",
"EXTENSIONID": 72,
"Id": 119
}
Create Many (streamed)
|
DESCRIPTION |
Use this method to create data for one or more user record(s) in a specific user list. It is not possible to insert any profile extensions. For this call it is required to provide the fields which will be posted on the first line, pipe-separated. |
||||||||
|
Key |
Profiles-Post-Stream |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/profiles/post?mode={create/append} |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/stream/lists/210/actions/post?mode=append
Name | Mail
{"Name": "John Doe 1", "Mail": "John1@test.com"}
{"Name": "John Doe 2", "Mail": "John2@test.com"}
{"Name": "John Doe 3", "Mail": "John3@test.com"}
…HTTP 200 OK
No additional content is returned.
Read One
|
DESCRIPTION |
Use this method to retrieve information on a specific user record in a specific user list. The scope can be limited by specifying the fields in the url of the request. |
||||||||
|
Key |
Profiles-Get-Id |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/profiles/{pid}{?fields=x,y,z} /restapi/api/async/lists/{id}/profiles/{pid}{?fields=x,y,z} |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP GET http://someserver.com/restapi/api/sync/lists/411/profiles/14?fields=id,mail,social_linkedin.firstname,social_linkedin.lastname In the above example a user record with id=14 is retrieved from the userlist with id=411. The fields returned are limited to the 'id', 'mail' and 'firstname' and 'lastname' in the profile extension 'social_linkedin'
{
"ID": 14,
"MAIL": "filip@wolkjes.net",
"SOCIAL_LINKEDIN.FIRSTNAME": "Filip",
"SOCIAL_LINKEDIN.LASTNAME": "LeRoi",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/411/profiles/14?fields=id,mail,social_linkedin.firstname,social_linkedin.lastname",
"verb": "GET"
}, {
"rel": "list",
"uri": "restapi/api/sync/lists/411",
"verb": "GET"
}]
}The _links section provides an overview of all other actions that can be performed on the resource.
Read All (paged)
|
DESCRIPTION |
Use this method to retrieve all user records from a specific user list. The scope can be limited by specifying the fields in the url. When including fields from 1:1 relations, which in reality contain 1:n data, multiple records of the same profile are returned. |
||||||||
|
Key |
Profiles-Get |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/profiles{?fields=x,y,z} /restapi/api/async/lists/{id}/profiles{?fields=x,y,z} |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
Yes |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
{
"result": [{
"ID": 340967,
"MAIL": "jane.doe0@gmail.com",
"NAME": "Doe0",
"OPTOUT": 0,
"TESTUSER": 0,
"ONLY_TEXT": null,
"OPTOUT_SOURCE": null,
"SUBSCRIBE_SOURCE": null,
"CREATED_DT": "2010-01-29T07:25:00",
"MODIFIED_DT": null,
"OPTOUT_DT": null,
"FIRSTNAME": "Jane 0",
"ADDRESS_STREET": null,
"ADDRESS_STREET_NUMBER": null,
"ADDRESS_STREET_BOX": null,
"ADDRESS_ZIP_CODE": null,
"ADDRESS_CITY": null,
"ADDRESS_COUNTRY": null,
"PHONE_MOBILE": null,
"PHONE_FIX": null,
"BIRTHDAY": null,
"GENDER": "F",
"LANG": null,
"PHONE": null,
"OPTIN": null,
"CAMPAIGN": null,
"MOBILE": null,
"DESTINATION": null,
"FRIENDID": null,
"DISCOUNT": null,
"CATEGORY": null,
"PRODUCTS": "\r",
"COUNTRY_CODE": null,
"FAVOURITE_BRAND": null,
"TMP_DATE": null,
"JGO_TEST": null
}, ...],
"total": 170489,
"_links": [{
"rel": "next",
"uri": "/restapi/api/sync/lists/1/profiles?offset=201&size=200",
"verb": "GET"
}]
}A total of 170.489 user records are in the user list. Paging is provided and returns 200 records per page.
All fields in the userlist are returned.
HTTP GET http://someserver.com/restapi/api/sync/lists/1/profiles?fields=id,mail,name,firstname,phone_mobile
Read All (streamed)
|
DESCRIPTION |
Use this method to retrieve all user records from a specific user list in streaming. The scope can be limited by specifying the fields in the url of the request. When including fields from 1:1 relations, which in reality contain 1:n data, multiple records of the same profile are returned. |
||||||||
|
Key |
Profiles-Get-Stream |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/profiles{?fields=x,y,z} |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
HTTP GET http://someserver.com/restapi/api/stream/lists/1/profilesHTTP 200 OK
First result:
{
"ID": 467345,
"MAIL": "john.doe126378@planet.nl",
"NAME": "Doe126378",
"OPTOUT": 0,
"TESTUSER": 0,
"ONLY_TEXT": null,
"OPTOUT_SOURCE": null,
"SUBSCRIBE_SOURCE": null,
"CREATED_DT": "2011-11-23T01:04:15.263",
"MODIFIED_DT": null,
"OPTOUT_DT": null,
"FIRSTNAME": "John 126378",
"ADDRESS_STREET": null,
"ADDRESS_STREET_NUMBER": null,
"ADDRESS_STREET_BOX": null,
"ADDRESS_ZIP_CODE": null,
"ADDRESS_CITY": null,
"ADDRESS_COUNTRY": null,
"PHONE_MOBILE": null,
"PHONE_FIX": null,
"BIRTHDAY": null,
"GENDER": "M",
"LANG": null,
"PHONE": null,
"OPTIN": null,
"CAMPAIGN": null,
"MOBILE": null,
"DESTINATION": null,
"FRIENDID": null,
"DISCOUNT": null,
"CATEGORY": null,
"PRODUCTS": "\r",
"COUNTRY_CODE": null,
"FAVOURITE_BRAND": null,
"TMP_DATE": null,
"JGO_TEST": null
}
HTTP GET http://someserver.com/restapi/api/stream/lists/1/profiles?fields=id,mail,name{
"ID": 467345,
"MAIL": "john.doe126378@planet.nl",
"NAME": "Doe126378"
}
Modify One
|
DESCRIPTION |
Use this method to update an existing user record in a specific user list. It is possible to update data in 1:1 profile extensions as well. |
||||||||
|
Key |
Profiles-Put |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/profiles/{pid} /restapi/api/async/lists/{id}/profiles/{pid} |
||||||||
|
Method |
PUT |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP PUT http://someserver.com/restapi/api/sync/lists/863/profiles/119
{
"Name": "User Test",
"ActionTriggerlink.ActionId": 1,
"Extensions.TwitterHandle": "@Suddenelfilio",
"Domains.MailDomain": "Selligent.be"
}{
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/863/profiles/119",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/863/profiles/119",
"verb": "PUT"
}, {
"rel": "list",
"uri": "restapi/api/sync/lists/863",
"verb": "GET"
}]
}
Search (paged)
|
DESCRIPTION |
Use this method to search for a specific profile in a specific user list. The result is depending on the fields in the list and profile extensions, as well as on the filters applied. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same profile will be returned |
||||||||
|
Key |
Profiles-Search |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/profiles/search /restapi/api/async/lists/{id}/profiles/search |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
Yes |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
When performing a search request, it is possible to define the scope of the result by specifying the fields you want to retrieve. The requested fields are separated by a colon.
Note: Because the POST method is used, the parameters are not added to the URL itself but in the payload.
HTTP POST http://someserver.com/restapi/api/sync/lists/411/profiles/search
{
"fields": ["id", "mail", "gender"],
"filter": {
"mail": "somemail@hotmail.com",
"op": "="
}
}HTTP 200 OK
{
"result": [{
"ID": "1",
"MAIL": "somemail@hotmail.com",
"GENDER": "M"
}, {
"ID": "2",
"MAIL": "somemail@hotmail.com",
"GENDER": "F"
}, {
"ID": "3",
"MAIL": "somemail@hotmail.com",
"GENDER": "F"
}, {
"ID": "4",
"MAIL": "somemail@hotmail.com",
"GENDER": "F"
}, {
"ID": "5",
"MAIL": "somemail@hotmail.com",
"GENDER": "M"
}, {
"ID": "6",
"MAIL": "somemail@hotmail.com",
"GENDER": "M"
}],
"total": 6,
"_links": []
}When a search is performed, at least one filter is applied on one or more fields
Note: Defining at least one filter is mandatory, else a HTTP 400 bad request will be returned!
Where
-
"Fieldname" is the actual name of the field in the list on which the filter is applied.
-
"Filtervalue" is the actual value to filter on for the specified fieldname.
-
"Op" is an indication that what follows is the operator used. This cannot be changed.
-
"Operator" is the actual operator to use. The following operators are supported: <, >, =, >=, <=, <>, Is Null
HTTP POST http://someserver.com/restapi/api/sync/lists/411/profiles/search
{
"fields": null,
"filter": {
"mail": "somemail@hotmail.com",
"op": "="
}
}HTTP 200 OK
{
"result": [{
"ID": 1,
"MAIL": "somemail@hotmail.com",
"NAME": "Test 01",
"OPTOUT": 0,
"TESTUSER": 1,
"ONLY_TEXT": null,
"OPTOUT_SOURCE": null,
"SUBSCRIBE_SOURCE": null,
"CREATED_DT": "2010-07-11T16:44:00",
"MODIFIED_DT": null,
"OPTOUT_DT": null,
"GENDER": "M",
"FIRSTNAME": "John"
}, ...],
"total": 13,
"_links": []
}The result returns an array of profiles responding to the filter in the request. All available fields in the user list are returned.
HTTP POST http://someserver.com/restapi/api/sync/lists/411/profiles/search
{
"fields": null,
"filter": {
"mail": "",
"op": "IS NULL"
}
}It is equally possible to combine filters.
By using AND and OR statements multiple filter expressions can be combined. Filters can equally be nested.
HTTP POST http: //someserver.com/restapi/api/sync/lists/411/profiles/search
{
"fields": null,
"filter": {
"and": [{
"mail": "somemail@hotmail.com",
"op": "="
}, {
"gender": "M",
"op": "="
}]
}
}The filter uses the AND operator to combine two filters, one on the email and one on the gender of the profile.
HTTP 200 OK
{
"result": [{
"ID": 1,
"MAIL": "somemail@hotmail.com",
"NAME": "Test 01",
"OPTOUT": 0,
"TESTUSER": 1,
"ONLY_TEXT": null,
"OPTOUT_SOURCE": null,
"SUBSCRIBE_SOURCE": null,
"CREATED_DT": "2010-07-11T16:44:00",
"MODIFIED_DT": null,
"OPTOUT_DT": null,
"GENDER": "M",
"FIRSTNAME": "John"
}, {
"ID": 2,
"MAIL": "somemail@hotmail.com",
"NAME": "Test 02",
"OPTOUT": 1,
"TESTUSER": 1,
"ONLY_TEXT": null,
"OPTOUT_SOURCE": null,
"SUBSCRIBE_SOURCE": null,
"CREATED_DT": "2011-02-03T06:50:00",
"MODIFIED_DT": null,
"OPTOUT_DT": "2011-02-27T23:02:35",
"GENDER": "M",
"FIRSTNAME": "John"
}, {
"ID": 4,
"MAIL": "somemail@hotmail.com",
"NAME": "Test 03",
"OPTOUT": 1,
"TESTUSER": 1,
"ONLY_TEXT": null,
"OPTOUT_SOURCE": null,
"SUBSCRIBE_SOURCE": null,
"CREATED_DT": "2010-03-16T21:20:00",
"MODIFIED_DT": null,
"OPTOUT_DT": "2010-10-08T15:52:51",
"GENDER": "M",
"FIRSTNAME": "John"
}, …],
"total": 13,
"_links": []
}Retrieving information from the 1:1 profile extension and applying filter on these profile extensions is equally possible.
To do so, the name of the profile extension scope must prefix the field name. To retrieve information on profile extensions for a list use the method indicated in section DESCRIPTION.
HTTP POST http://someserver.com/restapi/api/sync/lists/411/profiles/search
{
"fields": ["id", "mail", "gender", "social_linkedin.firstname", "social_linkedin.lastname"],
"filter": {
"social_linkedin.firstname": "Filip",
"op": "="
}
}In the above request, the fields 'ID', 'mail' and 'gender' are retrieved from the user list. The fields 'firstname' and 'lastname' are added from the profile extension 'social_linkedin'. A filter is applied on the field 'firstname' in the profile extension.
{
"result": [{
"ID": 14,
"MAIL": "filip@xxzz.net",
"GENDER": null,
"SOCIAL_LINKEDIN.FIRSTNAME": "Filip",
"SOCIAL_LINKEDIN.LASTNAME": "LeRoi"
}, ...],
"total": 11,
"_links": []
}
Search (streamed)
|
DESCRIPTION |
Use this method to search for a specific profile in a specific user list but without buffering the response. The same functionalities are available as when performing this request in asynchronous or synchronous mode. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same profile will be returned |
||||||||
|
Key |
Profiles-Search-Streamed |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/profiles/search |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/stream/lists/411/profiles/search
{"fields": ["id", "mail", "gender", "social_linkedin.firstname", "social_linkedin.lastname"], "filter": {"social_linkedin.firstname": "Filip", "op": "="}}HTTP 200 OK
First result:
{
"id": 1,
"MAIL": "filip@yyzz.net",
"GENDER": null,
"SOCIAL_LINKEDIN.FIRSTNAME": "Filip",
"SOCIAL_LINKEDIN.LASTNAME": "LeRoi"
}
Second result:
{
"id": 2,
"MAIL": "filip@soemwhat.net",
"GENDER": "M",
"SOCIAL_LINKEDIN.FIRSTNAME": "Filip",
"SOCIAL_LINKEDIN.LASTNAME": "Wuyts"
}
Lists Relations
Create One
|
DESCRIPTION |
Use this method to create a list relation. Only 1:1 and 1:N relations can be created. All fields are mandatory. The provided master and slave fields are checked for existence against their respective tables. |
||||||||
|
Key |
Relations-Post |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/relations /restapi/api/async/lists/{id}/relations |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/sync/lists/868/relations
{
"master_field": "ID",
"slave": 131,
"slave_field": "TESTFIELD_ID",
"scope": "DATA_TEST_API",
"name": "DATA_TEST",
"type": "1:1"
}HTTP 200 OK
{
"id": 15,
"master": 868,
"master_field": "ID",
"slave": 131,
"slave_field": "TESTFIELD_ID",
"scope": "DATA_TEST_API",
"name": "DATA_TEST",
"type": "1:1",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/868/relations",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/868/relations/15",
"verb": "PUT"
}, {
"rel": "master",
"uri": "restapi/api/sync/lists/868",
"verb": "GET"
}, {
"rel": "slave",
"uri": "restapi/api/sync/lists/131",
"verb": "GET"
}]
}The _links section provides insight in all other actions that can be performed on the list relation.
Read Many
|
DESCRIPTION |
Use this method to retrieve the relations for one specific list by using the ID of the list |
||||||||
|
Key |
Relations-Get |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/relations /restapi/api/async/lists/{id}/relations |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP 200 OK
[{
"id": 15,
"master": 1,
"master_field": "ID",
"slave": 4,
"slave_field": "USERID",
"scope": "EXT_VIRAL_PRODUCTASSIGN",
"name": "EXT_VIRAL_PRODUCTASSIGN",
"type": "1:1",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1/relations",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1/relations/15",
"verb": "PUT"
}, {
"rel": "master",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}, {
"rel": "slave",
"uri": "restapi/api/sync/lists/4",
"verb": "GET"
}]
},
...
]The result contains an array of relations with information on
- Id: the id of the relation
- master: the id of the master list
- master_field: the fieldname of the master list that links to the slave list
- slave: the id of the slave list
- slave_field: the fieldname of the slave list that links to the master list
- scope: the scope of the list extension
- name: the name of the list extension
- type: indicates if this is a 1:1 (profile extension) or 1:n list extension
- _links: other actions available on relations.
Modify One
|
DESCRIPTION |
Use this method to modify a list relation. Fields with no change must be supplied with value ‘null’. The provided master and slave fields are checked for existence against their respective tables. When a slave field is changed, the respective list id must also be provided and vice versa. |
||||||||
|
Key |
Relations-Put |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/relations/15 /restapi/api/async/lists/{id}/relations/15 |
||||||||
|
Method |
PUT |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP PUT http://someserver.com/restapi/api/sync/lists/1/relations/520
{
"id": 520,
"master_field": null,
"slave": 131,
"slave_field": "ANSWER",
"scope": null,
"name": null,
"type": null
}HTTP 200 OK
{
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1/relations",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1/relations/520",
"verb": "PUT"
}, {
"rel": "master",
"uri": "restapi/api/sync/lists/8",
"verb": "GET"
}, {
"rel": "slave",
"uri": "restapi/api/sync/lists/131",
"verb": "GET"
}]
}The _links section provides insight in all other actions that can be performed on the list relation.
Listfields
|
Use this method to add a field to the list |
|||||||||
|
Key |
ListField-Post |
||||||||
|
Path |
/restapi/api/sync/lists/{ListId}/fields /restapi/api/async/lists/{ListId}/fields |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/sync/lists/1/fields
{
{
"column": "street",
"dataType": "text",
"maxLength": 50,
"optionlist": 1,
"required": false
}
}HTTP 200 OK
{
{
"column": "street",
"primary_key": false,
"dataType": "text",
"maxLength": 50,
"optionlist": 1,
"required": false
}, "_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1/fields/street",
"verb": "PUT"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1/fields/street",
"verb": "DELETE"
}, {
"rel": "options",
"uri": "restapi/api/sync/optionlists/1",
"verb": "GET"
}, {
"rel": "list",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}]
}The _links section provides insight in all other actions that can be performed on the list field.
Modify One
|
DESCRIPTION |
Use this method to update a listfield |
||||||||
|
Key |
ListField-Put |
||||||||
|
Path |
/restapi/api/sync/lists/{listid}/fields/{fieldName} /restapi/api/async/lists/{ listid}/fields/{fieldName} |
||||||||
|
Method |
PUT |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP PUT http://someserver.com/restapi/api/sync/lists/1/fields/street
{
{
"column": "street",
"dataType": "text",
"maxLength": 50,
"optionlist": 1,
"required": false
}
}HTTP 200 OK
{
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/lists/1/fields/street",
"verb": "PUT"
}, {
"rel": "self",
"uri": "restapi/api/sync/lists/1/fields/street",
"verb": "DELETE"
}, {
"rel": "list",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}]
}The _links section provides insight in all other actions that can be performed on the list schema.
Delete One
|
DESCRIPTION |
Use this method to delete a field from a list |
||||||||
|
Key |
ListField-Delete |
||||||||
|
Path |
/restapi/api/sync/lists/{listId}/fields/{fieldName} /restapi/api/async/lists/{listId}/fields/{fieldName} |
||||||||
|
Method |
DELETE |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP 200 OK
{
"_links": [{
"rel": "list",
"uri": "restapi/api/sync/lists/1",
"verb": "GET"
}]
}
Optionlists
Read One
|
DESCRIPTION |
Use this method to retrieve the option list values for a specific field in a specific list by using the ID of the list. The optionlist ID is required in the request as well and can be obtained from the result returned when retrieving the scheme of that specific list. |
||||||||
|
Key |
Options-Get |
||||||||
|
Path |
/restapi/api/sync/optionlists/{optionlistID} /restapi/api/async/optionlists/{optionlistID} |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP 200 OK
{
"available_languages": "EN,NL,FR",
"languages": [{
"language": "EN",
"options": [{
"index": 1,
"code": "M",
"value": "Male"
}, {
"index": 2,
"code": "F",
"value": "Female"
}]
}, {
"language": "FR",
"options": [{
"index": 2,
"code": "F",
"value": "Femme"
}, {
"index": 1,
"code": "M",
"value": "Homme"
}]
}, {
"language": "NL",
"options": [{
"index": 1,
"code": "M",
"value": "Man"
}, {
"index": 2,
"code": "F",
"value": "Vrouw"
}]
}],
"name": "Gender",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/232",
"verb": "GET"
}, {
"rel": "en-values",
"uri": "restapi/api/sync/optionlists/232/en",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/232/nl",
"verb": "GET"
}, {
"rel": "fr-values",
"uri": "restapi/api/sync/optionlists/232/fr",
"verb": "GET"
}]
}The result returns
- available_languages: the language codes that have translations
- languages: for each language the options will be listed with their translated value
- index: the location of the option in a list
- code: the option code
- value: the translated value for the code.
- name: the option list name
- _links: links other actions available on option lists.
To retrieve the option list values for a specific language, simply pass on the language in the URL as well.
Note: The _links in the result of the request for optionlist values, indicates also what you need to do to retrieve this information.
HTTP GET http://someserver.com/restapi/api/sync/optionlists/232/enHTTP 200 OK
{
"available_languages": "EN,NL,FR",
"languages": [{
"language": "EN",
"options": [{
"index": 1,
"code": "M",
"value": "Male"
}, {
"index": 2,
"code": "F",
"value": "Female"
}]
}],
"name": "Gender",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/232",
"verb": "GET"
}, {
"rel": "en-values",
"uri": "restapi/api/sync/optionlists/232/en",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/232/nl",
"verb": "GET"
}, {
"rel": "fr-values",
"uri": "restapi/api/sync/optionlists/232/fr",
"verb": "GET"
}]
}
Get all optionlists
|
DESCRIPTION |
Use this method to retrieve a list of available optionlists. |
||||||||
|
Key |
OptionLists-Get |
||||||||
|
Path |
/restapi/api/sync/optionlists /restapi/api/sync/optionlists?offset=1&size=200 |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
yes |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
{
"result": [{
"available_languages": ["EN", "NL"],
"id": 1,
"name": "Gender",
"description": "The possible gender types.",
"sqlquery": null,
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/1",
"verb": "GET"
}, {
"rel": "en-values",
"uri": "restapi/api/sync/optionlists/1/en",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/1/nl",
"verb": "GET"
}]
}, {
"available_languages": ["NL"],
"id": 3,
"name": "COMPANY",
"description": "A list of companies",
"sqlquery": null,
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/3",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/3/nl",
"verb": "GET"
}]
}],
"total": 2,
"_links": []
}
Create optionlist (SQL)
|
DESCRIPTION |
Use this method to create an optionlist based on a sqlquery. Remarks:
|
||||||||
|
Key |
Options-Post |
||||||||
|
Path |
/restapi/api/sync/optionlists |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/sync/optionlists
{
"name": "rest option list",
"description": "Description here",
"sqlquery": "SELECT 123 AS CODE, 'eentweedrie' AS NL, 'undeuxtrois' as FR FROM MYCUSTOMOPTIONS"
"available_languages": "NL,FR"
}HTTP 200 OK
{
"available_languages": ["NL", "FR"],
"languages": [{
"language": "NL",
"options": [{
"index": 0,
"code": "123",
"value": "eentweedrie"
}]
}, {
"language": "FR",
"options": [{
"index": 1,
"code": "123",
"value": "undeuxtrois"
}]
}],
"id": 11,
"name": "rest option list",
"description": "Description here",
"sqlquery": " SELECT 123 AS CODE, 'eentweedrie' AS NL, 'undeuxtrois' as FR",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/11",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/11/nl",
"verb": "GET"
}, {
"rel": "fr-values",
"uri": "restapi/api/sync/optionlists/11/fr",
"verb": "GET"
}]
}
Create optionlist (code)
|
DESCRIPTION |
Use this method to create an optionlist. Remarks:
|
||||||||
|
Key |
Options-Post |
||||||||
|
Path |
/restapi/api/sync/optionlists |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/sync/optionlists
{
"name": "rest option list",
"description": "Description here",
"available_languages": "NL,FR",
"languages": [{
"language": "NL",
"options": [{
"code": "code1",
"value": "value1 NL"
}, {
"code": "code2",
"value": "value2 NL"
}, {
"code": "code3",
"value": "value3 NL"
}]
}, {
"language": "FR",
"options": [{
"code": "code1",
"value": "value1 FR"
}, {
"code": "code3",
"value": "value3 FR"
}]
}]
}HTTP 200 OK
{
"available_languages": ["NL", "FR"],
"languages": [{
"language": "FR",
"options": [{
"index": 0,
"code": "code1",
"value": "value1 fr"
}, {
"index": 1,
"code": "code3",
"value": "value3 fr"
}]
}, {
"language": "NL",
"options": [{
"index": 0,
"code": "code1",
"value": "value1 nl"
}, {
"index": 1,
"code": "code2",
"value": "value2 nl"
}, {
"index": 2,
"code": "code3",
"value": "value3 nl"
}]
}],
"id": 10,
"name": "rest option list",
"description": "Description here",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/10",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/10/nl",
"verb": "GET"
}, {
"rel": "fr-values",
"uri": "restapi/api/sync/optionlists/10/fr",
"verb": "GET"
}]
}
Update optionlist
|
DESCRIPTION |
Use this method to update an optionlist. Remarks:
|
||||||||
|
Key |
Options-Post |
||||||||
|
Path |
/restapi/api/sync/optionlists/{id} |
||||||||
|
Method |
PUT |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP PUT http://someserver.com/restapi/api/sync/optionlists/1
{
"name": "rest option list",
"description": "Description here",
"sqlquery": " SELECT 123 AS CODE, 'eentweedrie' AS NL, 'undeuxtrois' as FR FROM MYCUSTOMOPTIONS"
"available_languages": "NL,FR"
}HTTP 200 OK
{
"available_languages": ["NL", "FR"],
"languages": [{
"language": "FR",
"options": [{
"index": 0,
"code": "code1",
"value": "value1 fr"
}, {
"index": 1,
"code": "code3",
"value": "value3 fr"
}]
}, {
"language": "NL",
"options": [{
"index": 0,
"code": "code1",
"value": "value1 nl"
}, {
"index": 1,
"code": "code2",
"value": "value2 nl"
}, {
"index": 2,
"code": "code3",
"value": "value3 nl"
}]
}],
"id": 10,
"name": "rest option list",
"description": "Description here",
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/10",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/10/nl",
"verb": "GET"
}, {
"rel": "fr-values",
"uri": "restapi/api/sync/optionlists/10/fr",
"verb": "GET"
}]
}
Delete optionlist
|
DESCRIPTION |
Use this method to delete an optionlist |
||||||||
|
Key |
Options-Delete |
||||||||
|
Path |
/restapi/api/sync/optionlists/{id} |
||||||||
|
Method |
DELETE |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
Add option
|
DESCRIPTION |
Use this method to add an option to an optionlist. Remarks: Returns an error if the optionlist was defined with a sql query |
||||||||
|
Key |
Options-Post-Option |
||||||||
|
Path |
/restapi/api/sync/optionlists/{optionlistId}/options |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP POST http://someserver.com/restapi/api/sync/optionlists/1/options
{
"code": "code5",
"languages": [{
"language": "NL",
"value": "value1 NL"
}, {
"language ": "FR",
"value": "value1 FR"
}]
}HTTP 200 OK
{
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/9",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/9/nl",
"verb": "GET"
}, {
"rel": "fr-values",
"uri": "restapi/api/sync/optionlists/9/fr",
"verb": "GET"
}]
}
Update option
|
DESCRIPTION |
Use this method to update an option in an optionlist. Remarks: Returns an error if the optionlist was defined with a sql query |
||||||||
|
Key |
Options-Put-Option |
||||||||
|
Path |
/restapi/api/sync/optionlists/{optionlistId}/options |
||||||||
|
Method |
PUT |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP PUT http://someserver.com/restapi/api/sync/optionlists/1/options
{
"code": "code5",
"languages ": [{
"language ": "NL ",
"value ": "value1 NL "
},
{
"language ": "FR ",
"value ": "value1 FR "
}
]
}HTTP 200 OK
{
"_links": [{
"rel": "self",
"uri": "restapi/api/sync/optionlists/9",
"verb": "GET"
}, {
"rel": "nl-values",
"uri": "restapi/api/sync/optionlists/9/nl",
"verb": "GET"
}, {
"rel": "fr-values",
"uri": "restapi/api/sync/optionlists/9/fr",
"verb": "GET"
}]
}
Delete option
|
DESCRIPTION |
Use this method to delete an option in an optionlist. Remarks: Returns an error if the optionlist was defined with a sql query |
||||||||
|
Key |
Options-Delete-Option |
||||||||
|
Path |
/restapi/api/sync/optionlists/{optionlistId}/options |
||||||||
|
Method |
PUT |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP DELETE http://someserver.com/restapi/api/sync/optionlists/1/options
{
"code": "code5"
}
Article lists
Create Article list
|
DESCRIPTION |
Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property. |
||||||||
|
Key |
Lists-post |
||||||||
|
Path |
/restapi/api/sync/lists /restapi/api/async/lists |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
POST restapi/api/sync/lists
Post body:
{
"name": "ARTICLE_EXAMPLE_LIST",
"type": "ARTICLELIST",
"folder": 1964,
"owner": 279,
"disabled": 0,
"fields": [{
"column": "title",
"dataType": "text",
"maxLength": 50,
"required": true
}, {
"column": "description",
"dataType": "long text",
"maxLength": 50,
"required": false
}, {
"column": "art_int",
"dataType": "numeric",
"required": true
}, {
"column": "art_long",
"dataType": "long",
"required": false
}, {
"column": "art_float",
"dataType": "float",
"required": true
}, {
"column": "art_datetime",
"dataType": "datetime",
"required": true
}, {
"column": "art_date",
"dataType": "date",
"required": true
}, {
"column": "art_boolean",
"dataType": "boolean",
"required": false
}]
}HTTP 200 OK
{
"id": 4177,
"type": "ARTICLELIST",
"tablename": "DB_DATA.dbo.ARTICLES_ ARTICLE_EXAMPLE_LIST ",
"name": " ARTICLE_EXAMPLE_LIST ",
"description": null,
"folder": 1964,
"owner": 279,
"disabled": 0,
"fields": [{
"column": "ID",
"primary_key": true,
"required": true,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric",
"_links": [{
"rel": "self",
"uri": "restapi/api/async/lists/4177/fields/id",
"verb": "PUT"
}, {
"rel": "self",
"uri": "restapi/api/async/lists/4177/fields/id",
"verb": "DELETE"
}]
}, …],
"_links": [{
"rel": "self",
"uri": "restapi/api/async/lists/4177",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/async/lists/4177",
"verb": "PUT"
}, ]
}
Create one article
|
DESCRIPTION |
Use this method to create data for one specific article list entry by providing the desired input. All fields are checked for existence against the article list table. |
||||||||
|
Key |
ArticleList-Post |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/articles |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
POST restapi/api/sync/lists/111/articles
Post body:
{
"title": "art title",
"ART_INT": 1,
"ART_FLOAT": 1.25
}HTTP 200 OK
{
"title": "art title",
"ART_INT": 1,
"ART_FLOAT": 1.25,
"CREATED_DT": "2016-10-21T16:15:07.8087164+02:00",
"Id": 1
}
Create many articles (streamed)
|
DESCRIPTION |
Use this method to create data for one or many article list entries by providing the desired input. All fields are checked for existence against the article list table. For this call it is required to provide the fields which will be posted on the first line, pipe-separated. |
||||||||
|
Key |
ArticleList-Post-Stream |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/articles/post?mode=append |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
POST restapi/api/stream/lists/111/articles/post?mode=append
TITLE|art_int|art_float
{"TITLE": "title", "art_int": 1, "art_float": 1.25}
{"TITLE": "title", "art_int": 2, "art_float": 1.25}
{"TITLE": "title", "art_int": 3, "art_float": 1.25}
{"TITLE": "title", "art_int": 4, "art_float": 1.25}
{"TITLE": "title", "art_int": 5, "art_float": 1.25}
{"TITLE": "title", "art_int": 6, "art_float": 1.25}
{"TITLE": "title", "art_int": 7, "art_float": 1.25}
{"TITLE": "title", "art_int": 8, "art_float": 1.25}
{"TITLE": "title", "art_int": 9, "art_float": 1.25}
{"TITLE": "title", "art_int": 0, "art_float": 1.25}HTTP 200 OK
No additional content is returned.
Delete one article
|
DESCRIPTION |
Use this method to delete a specific article record in a specific article list. |
||||||||
|
Key |
ArticleList-Delete-Id |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/articles/{ArticleId} |
||||||||
|
Method |
DELETE |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
||||||||
|
Quota |
|
HTTP 200 OK
No additional content is returned.
Read one article
|
DESCRIPTION |
Use this method to retrieve information on a specific article record in a specific article list. |
||||||||
|
Key |
ArticleList-Get-Id |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/articles/{articleId} |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
{
"ID": 1,
"CREATED_DT": "2016-10-21T16:15:07.81",
"MODIFIED_DT": null,
"TAXONOMY": null,
"TITLE": "art title",
"ART_INT": 1,
"ART_FLOAT": 1.25,
}
Read all articles (paged)
|
DESCRIPTION |
Use this method to retrieve multiple article records in a specific article list. |
||||||||
|
Key |
ArticleList-Get |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/articles |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
YES |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
{
"result": [{
"ID": 5,
"CREATED_DT": "2016-10-14T16:22:12.05",
"MODIFIED_DT": null,
"TAXONOMY": null,
"TITLE": "title",
"DESCRIPTION": null,
"ART_INT": 4,
"ART_LONG": null,
"ART_FLOAT": 1.25,
"ART_DATETIME": null,
"ART_DATE": null,
"ART_BOOLEAN": null
}, {
"ID": 6,
"CREATED_DT": "2016 - 10 14 T16: 22: 12.05",
"MODIFIED_DT": null,
"TAXONOMY": null,
"TITLE": "title ",
"DESCRIPTION": null,
"ART_INT": 5,
"ART_LONG": null,
"ART_FLOAT": 1.25,
"ART_DATETIME": null,
"ART_DATE": null,
"ART_BOOLEAN": null
}],
"total": 9,
"_links": [{
"rel": "prev",
"uri": "restapi/api/sync/lists/4028/articles?offset=3&size=2",
"verb": "GET"
}, {
"rel": "next",
"uri": "restapi/api/sync/lists/4028/articles?offset=7&size=2",
"verb": "GET"
}]
}
Read all articles (streamed)
|
DESCRIPTION |
Use this method to retrieve all article records in a specific article list. |
||||||||
|
Key |
ArticleList-Get-Stream |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/articles |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
NO |
||||||||
|
Stream support |
YES |
||||||||
|
Quota |
|
HTTP 200 OK
First result:
{
"ID": 1,
"CREATED_DT": "2016-10-14T16:22:02.373",
"MODIFIED_DT": null,
"TAXONOMY": null,
"TITLE": "arttitle",
"DESCRIPTION": null,
"ART_INT": 1,
"ART_LONG": null,
"ART_FLOAT": 1.25,
"ART_DATETIME": null,
"ART_DATE": null,
"ART_BOOLEAN": null
}
Modify one article
|
DESCRIPTION |
Use this method to update an article |
||||||||
|
Key |
ArticleList-Put-Id |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/articles/{articleId} /restapi/api/async/lists/{id}/articles/{articleId} |
||||||||
|
Method |
Put |
||||||||
|
Paging support |
NO |
||||||||
|
Stream support |
NO |
||||||||
|
Quota |
|
PUT restapi/api/sync/lists/4028/articles
Put body:
{
"title": "art updated",
"ART_DATETIME": "2016-10-20T16:22:12.05"
}HTTP 200 OK
Search (paged)
|
DESCRIPTION |
Use this method to search for a specific article in a specific article list. The result is depending on the fields in the list and extensions, as well as on the filters applied. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same article will be returned |
||||||||
|
Key |
ArticleList-Search |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/articles/search /restapi/api/async/lists/{id}/articles/search |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
Yes |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
POST http://someserver.com/api/sync/lists/411/articles/search
Post body:
{
"fields": ["id", "title", "content"],
"filter": {
"title": "some title",
"op": "="
}
}HTTP 200 OK
{
"result": [{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}, {
"ID": "2",
"TITLE": "some title",
"CONTENT": "some text"
}, {
"ID": "3",
"TITLE": "some title",
"CONTENT": "some text"
}],
"total": 3,
"_links": []
}Rest is the same as “Search Paged in List Profiles”
Search (streamed)
|
DESCRIPTION |
Use this method to search for a specific article in a specific article list but without buffering the response. The same functionalities are available as when performing this request in asynchronous or synchronous mode. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same article will be returned. |
||||||||
|
Key |
ArticleList-Search-Streamed |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/articles/search |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
POST http://someserver.com/api/stream/lists/411/articles/search
Post body:
{
"fields": ["id", "title", "content"],
"filter": {
"title": "some title",
"op": "="
}
}HTTP 200 OK
First result:
{
{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}
}
Second result:
{
{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}
}
Product lists
Create Product list
|
DESCRIPTION |
Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property. |
||||||||
|
Key |
Lists-post |
||||||||
|
Path |
/restapi/api/sync/lists /restapi/api/async/lists |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
NO |
||||||||
|
Stream support |
NO |
||||||||
|
Quota |
|
POST restapi/api/sync/lists
Post body:
{
"name": "PROD_EXAMPLE_LIST",
"type": "PRODUCTLIST",
"folder": 1964,
"owner": null,
"fields": [{
"column": "title",
"dataType": "text",
"maxLength": 50,
"required": true
}, {
"column": "description",
"dataType": "long text",
"maxLength": 50,
"required": false
}, {
"column": "prod_int",
"dataType": "numeric",
"maxLength": 50,
"required": true
}, {
"column": "prod_long",
"dataType": "long",
"required": false
}, {
"column": "prod_float",
"dataType": "float",
"required": true
}, {
"column": "prod_datetime",
"dataType": "datetime",
"required": true
}, {
"column": "prod_date",
"dataType": "date",
"required": true
}, {
"column": "prod_boolean",
"dataType": "boolean",
"required": false
}]
}HTTP 200 OK
{
"id": 4182,
"type": "PRODUCTLIST",
"tablename": "DB_DATA.dbo.PRODUCTS_PROD_EXAMPLE_LIST",
"name": "PROD_EXAMPLE_LIST",
"description": null,
"folder": 1964,
"owner": 279,
"disabled": null,
"fields": [{
"column": "ID",
"primary_key": true,
"required": true,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
},
...
],
"_links ": [{
"rel": "self ",
"uri ": "restapi/api/async/lists/4182",
"verb ": "GET "
}, {
"rel ": "self ",
"uri": "restapi/api/async/lists/4182",
"verb": "PUT "
}]
}
Create one product
|
DESCRIPTION |
Use this method to create data for one specific product list entry by providing the desired input. All fields are checked for existence against the product list table. |
||||||||
|
Key |
ProductList-post |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/products |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
NO |
||||||||
|
Stream support |
NO |
||||||||
|
Quota |
|
POST restapi/api/sync/lists/4022/products
Post body:
{
"title": "prod title",
"prod_int": 1,
"prod_float": 1.25
}HTTP 200 OK
{
"title": "prod title",
"prod_int": 1,
"prod_float": 1.25,
"CREATED_DT": "2016-10-21T16:34:34.9240738+02:00",
"Id": 2
}
Create many products (streamed)
|
DESCRIPTION |
Use this method to create data for one or many product list entries by providing the desired input. All fields are checked for existence against the product list table. For this call it is required to provide the fields which will be posted on the first line, pipe-separated. |
||||||||
|
Key |
ProductList-Post-Stream |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/products/post?mode=append |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
NO |
||||||||
|
Stream support |
YES |
||||||||
|
Quota |
|
POST restapi/api/stream/lists/4022/products/post?mode=append
TITLE|prod_int|prod_float
{"TITLE": "title", "prod_int": 1, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 2, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 3, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 4, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 5, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 6, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 7, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 8, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 9, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 0, "prod_float": 1.25}HTTP 200 OK
No additional content is returned.
Delete one product
|
DESCRIPTION |
Use this method to delete a specific product record in a specific product list. |
||||||||
|
Key |
ProductList-Delete-Id |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/products/{productId} |
||||||||
|
Method |
DELETE |
||||||||
|
Paging support |
NO |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
No additional content is returned.
Read one product
|
DESCRIPTION |
Use this method to retrieve information on a specific product record in a specific product list. |
||||||||
|
Key |
ProductList-Get-Id |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/products/{productId} |
||||||||
|
Method |
Get |
||||||||
|
Paging support |
NO |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
{
"ID": 1,
"CREATED_DT": "2016-10-21T16:34:07.513",
"TITLE": "prod title",
"DESCRIPTION": null,
"PROD_INT": 1,
"PROD_LONG": null,
"PROD_FLOAT": 1.25,
}
Read all products (paged)
|
DESCRIPTION |
Use this method to retrieve multiple product records in a specific article list. |
||||||||
|
Key |
ProductList-Get |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/products |
||||||||
|
Method |
Get |
||||||||
|
Paging support |
YES |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
{
"result": [{
"ID": 5,
"CREATED_DT": "2016-10-14T16:22:30.67",
"MODIFIED_DT": null,
"TITLE": "title",
"DESCRIPTION": null,
"PROD_INT": 4
}],
"total": 11,
"_links": [{
"rel": "prev",
"uri": "restapi/api/sync/lists/4029/products?offset=3&size=2",
"verb": "GET"
}, {
"rel": "next",
"uri": "restapi/api/sync/lists/4029/products?offset=7&size=2",
"verb": "GET"
}]
}
Read all products (streamed)
|
DESCRIPTION |
Use this method to retrieve all products records in a specific product list. |
||||||||
|
Key |
ProductList-Get-Stream |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/products |
||||||||
|
Method |
Get |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
YES |
||||||||
|
Quota |
|
HTTP 200 OK
First result :
{
"ID": 1,
"CREATED_DT": "2016-10 14T16:22:18.553",
"MODIFIED_DT": null,
"AVAILABLE_DT": null,
"RESERVED_DT": null,
"LOCK_DT": null,
"LOCK_TOKEN": null,
"ITEMTYPE": null,
"CAMPAIGNID": null,
"ACTIONID": null,
"LISTID": null,
"USERID": null,
"TITLE": "prod title",
"DESCRIPTION": null,
"PROD_INT": 1,
"PROD_LONG": null,
"PROD_FLOAT": 1.25,
"PROD_DATETIME": null,
"PROD_DATE": null,
"PROD_BOOLEAN": null
}
Modify one product
|
DESCRIPTION |
Use this method to update a product |
||||||||
|
Key |
ProductList-Put-Id |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/products/{productId} /restapi/api/async/lists/{id}/products/{productId} |
||||||||
|
Method |
Put |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
PUT restapi/api/sync/lists/4028/products
Put body:
{
"title": "product updated",
"PROD_DATETIME": "2016-10-20T16:22:12.05"
}HTTP 200 OK
Search (Paged)
|
DESCRIPTION |
Use this method to search for a specific product in a specific product list. The result is depending on the fields in the list and extensions, as well as on the filters applied. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same product will be returned. |
||||||||
|
Key |
ProductList-Search |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/products/search /restapi/api/async/lists/{id}/products/search |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
Yes |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
POST http://someserver.com/api/sync/lists/411/products/search
Post body:
{
"fields": ["id", "title", "content"],
"filter": {
"title": "some title",
"op": "="
}
}HTTP 200 OK
{
"result": [{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}, {
"ID": "2",
"TITLE": "some title",
"CONTENT": "some text"
}, {
"ID": "3",
"TITLE": "some title",
"CONTENT": "some text"
}],
"total": 3,
"_links": []
}Rest is the same as “Search Paged in List Profiles”
Search (streamed)
|
DESCRIPTION |
Use this method to search for a specific product in a specific product list but without buffering the response. The same functionalities are available as when performing this request in asynchronous or synchronous mode. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same product will be returned. |
||||||||
|
Key |
ProductList-Search-Streamed |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/products/search |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
POST http://someserver.com/api/stream/lists/411/products/search
Post body:
{
"fields": ["id", "title", "content"],
"filter": {
"title": "some title",
"op": "="
}
}HTTP 200 OK
First result:
{
{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}
}
Second result:
{
{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}
}
Data list
Create a data list
|
DESCRIPTION |
Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property. |
||||||||
|
Key |
Lists-post |
||||||||
|
Path |
/restapi/api/sync/lists /restapi/api/async/lists |
||||||||
|
Method |
Post |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
POST restapi/api/sync/lists
Post body:
{
"name": "EXAMPLE_DATA_LIST",
"type": "DATALIST",
"folder": 1964,
"owner": null,
"fields": [{
"column": "title",
"dataType": "text",
"maxLength": 50,
"required": false
}, {
"column": "description",
"dataType": "long text",
"maxLength": 50,
"required": false
}, {
"column": "data_int",
"dataType": "numeric",
"maxLength": 50,
"required": false
}]
}HTTP 200 OK
{
"id": 4266,
"type": "DATALIST",
"tablename": "DB_DATA.dbo.DATA_EXAMPLE_DATA_LIST",
"name": "EXAMPLE_DATA_LIST",
"description": null,
"folder": 1964,
"owner": 279,
"disabled": null,
"fields": [{
"column": "ID",
"primary_key": true,
"required": true,
"maxlength": 0,
"optionlist": 0,
"datatype": "Numeric"
}, {
"column": "title",
"primary_key": false,
"required": false,
"maxlength": 50,
"optionlist": 0,
"datatype": "Text"
}, {
"column": "description",
"primary_key": false,
"required": false,
"maxlength": 50,
"optionlist": 0,
"datatype": "Long Text"
}, {
"column": "data_int",
"primary_key": false,
"required": false,
"maxlength": 50,
"optionlist": 0,
"datatype": "Numeric"
}],
"_links": [{
"rel": "self",
"uri": "restapi/api/async/lists/4266",
"verb": "GET"
}, {
"rel": "self",
"uri": "restapi/api/async/lists/4266",
"verb": "PUT"
}]
}
Create one data record
|
DESCRIPTION |
Use this method to create data for one specific data list entry by providing the desired input. All fields are checked for existence against the data list table. |
||||||||
|
Key |
DataList-post |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/data |
||||||||
|
Method |
Post |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
{
"data_int": 1,
"Id": 2
}
Create many data records (streamed)
|
DESCRIPTION |
Use this method to create data for one or many data list entries by providing the desired input. All fields are checked for existence against the data list table. For this call it is required to provide the fields which will be posted on the first line, pipe-separated. |
||||||||
|
Key |
DataList-post-stream |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/data/post?mode=append |
||||||||
|
Method |
Post |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
YES |
||||||||
|
Quota |
|
POST restapi/api/stream/lists/111/data/post?mode=append
TITLE|data_int
{"TITLE": "title 1", "data_int": "1"}
{"TITLE": "title 2", "data_int": "2"}
{"TITLE": "title 2", "data_int": "3"}
{"TITLE": "title 4", "data_int": "4"}
{"TITLE": "title 5", "data_int": "5"}
{"TITLE": "title 6", "data_int": "6"}
{"TITLE": "title 7", "data_int": "7"}
{"TITLE": "title 8", "data_int": "8"}
{"TITLE": "title 9", "data_int": "9"}
{"TITLE": "title 10", "data_int": "10"}HTTP 200 OK
No additional content is returned.
Delete one data record
|
DESCRIPTION |
Use this method to delete a specific data record in a specific data list. |
||||||||
|
Key |
DataList-Delete-Id |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/data/{dataId} |
||||||||
|
Method |
Delete |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
No additional content is returned.
Read one data record
|
DESCRIPTION |
Use this method to retrieve information on a specific data record in a specific data list. |
||||||||
|
Key |
DataList-Get-Id |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/data/{dataId} |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
{
"ID": 12,
"TITLE": "title 10",
"DESCRIPTION": null,
"DATA_INT": 10
}
Read all data records (paged)
|
DESCRIPTION |
Use this method to retrieve multiple data records in a specific data list. |
||||||||
|
Key |
DataList-Get |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/data |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
YES |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
{
"result": [{
"ID": 6,
"TITLE": "title 4",
"DESCRIPTION": null,
"DATA_INT": 4
}, {
"ID": 7,
"TITLE": "title 5",
"DESCRIPTION": null,
"DATA_INT": 5
}],
"total": 11,
"_links": [{
"rel": "prev",
"uri": "restapi/api/sync/lists/4266/data?offset=3&size=2",
"verb": "GET"
}, {
"rel": "next",
"uri": "restapi/api/sync/lists/4266/data?offset=7&size=2",
"verb": "GET"
}]
}
Read all data records (streamed)
|
DESCRIPTION |
Use this method to retrieve multiple data records in a specific data list. |
||||||||
|
Key |
DataList-Get |
||||||||
|
Path |
/restapi/api/{mode}/lists/{id}/data |
||||||||
|
Method |
GET |
||||||||
|
Paging support |
YES |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
HTTP 200 OK
First result:
{
"ID": 2,
"TITLE": "data title",
"DESCRIPTION": null,
"DATA_INT": 1
}
Modify one data record
|
DESCRIPTION |
Use this method to update a data record. When updating multiple columns of a record of which one or more are non-existing columns, the REST API call will succeed and all existing columns will be updated. Non-existing columns are ignored. |
||||||||
|
Key |
DataList-Put-Id |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/data/{dataId} /restapi/api/async/lists/{id}/data/{dataId} |
||||||||
|
Method |
Put |
||||||||
|
Paging support |
NO |
||||||||
|
Stream support |
NO |
||||||||
|
Quota |
|
PUT restapi/api/sync/lists/4028/data
Put body:
{
"title": "data updated",
"DATA_INT": 2016
}HTTP 200 OK
Search (paged)
|
DESCRIPTION |
Use this method to search for a specific record in a specific data list. The result is depending on the fields in the list and extensions, as well as on the filters applied. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same record will be returned |
||||||||
|
Key |
DataList-Search |
||||||||
|
Path |
/restapi/api/sync/lists/{id}/data/search /restapi/api/async/lists/{id}/data/search |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
Yes |
||||||||
|
Stream support |
No |
||||||||
|
Quota |
|
POST http://someserver.com/api/sync/lists/411/data/search
Post body:
{
"fields": ["id", "title", "content"],
"filter": {
"title": "some title",
"op": "="
}
}HTTP 200 OK
{
"result": [{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}, {
"ID": "2",
"TITLE": "some title",
"CONTENT": "some text"
}, {
"ID": "3",
"TITLE": "some title",
"CONTENT": "some text"
}],
"total": 3,
"_links": []
}Rest is the same as “Search Paged in List Profiles”
Search (streamed)
|
DESCRIPTION |
Use this method to search for a specific record in a specific data list but without buffering the response. The same functionalities are available as when performing this request in asynchronous or synchronous mode. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same record will be returned |
||||||||
|
Key |
DataList-Search-Streamed |
||||||||
|
Path |
/restapi/api/stream/lists/{id}/data/search |
||||||||
|
Method |
POST |
||||||||
|
Paging support |
No |
||||||||
|
Stream support |
Yes |
||||||||
|
Quota |
|
POST http://someserver.com/api/stream/lists/411/data/search
Post body:
{
"fields": ["id", "title", "content"],
"filter": {
"title": "some title",
"op": "="
}
}HTTP 200 OK
First result:
{
{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}
}
Second result:
{
{
"ID": "1",
"TITLE": "some title",
"CONTENT": "some text"
}
}
Lists Segments
Read One
|
DESCRIPTION |
Use this method to retrieve data for one specific list segment by using the ID of the list and segment. |
|
Key |
Lists-Segments-Get-Id |
|
Path |
/restapi/api/sync/lists/{id}/segments/{id} /restapi/api/async/lists/{id}/segments/{id} |
|
Method |
GET |
|
Paging support |
No |
|
Stream support |
No |
|
Direct request support |
Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests. |
|
Quota |