From dc3864c472c787aea0786461e02d39dd850eba4a Mon Sep 17 00:00:00 2001 From: John Linhart Date: Thu, 19 May 2022 09:52:38 +0200 Subject: [PATCH 1/3] Unifying code example style --- source/includes/_api_endpoint_contacts.md | 65 ++++++++++++----------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/source/includes/_api_endpoint_contacts.md b/source/includes/_api_endpoint_contacts.md index 1920f0952b7..5d05ab00b39 100644 --- a/source/includes/_api_endpoint_contacts.md +++ b/source/includes/_api_endpoint_contacts.md @@ -22,6 +22,7 @@ $contactApi = $api->newApi("contacts", $auth, $apiUrl); $contact = $contactApi->get($id); ``` ```json + { "contact": { "id": 47, "dateAdded": "2015-07-21T12:27:12-05:00", @@ -105,6 +106,7 @@ $contact = $contactApi->get($id); } } } + } ``` Get an individual contact by ID. @@ -320,13 +322,13 @@ Same as [Get Contact](#get-contact). ```php 'Jim', 'lastname' => 'Contact', 'email' => 'jim@his-site.com', 'ipAddress' => $_SERVER['REMOTE_ADDR'], 'overwriteWithBlank' => true, -); +]; $contact = $contactApi->create($data); ``` @@ -358,20 +360,20 @@ Same as [Get Contact](#get-contact). ```php 'Jim', - 'lastname' => 'Contact', - 'email' => 'jim@his-site.com', - 'ipAddress' => $_SERVER['REMOTE_ADDR'] - ), - array( - 'firstname' => 'John', - 'lastname' => 'Doe', - 'email' => 'john@his-site.com', - 'ipAddress' => $_SERVER['REMOTE_ADDR'] - ) -); +$data = [ + [ + 'firstname' => 'Jim', + 'lastname' => 'Contact', + 'email' => 'jim@his-site.com', + 'ipAddress' => $_SERVER['REMOTE_ADDR'] + ], + [ + 'firstname' => 'John', + 'lastname' => 'Doe', + 'email' => 'john@his-site.com', + 'ipAddress' => $_SERVER['REMOTE_ADDR'] + ] +]; $contact = $contactApi->createBatch($data); ``` Create a batch of new contacts. @@ -402,10 +404,10 @@ Array of contacts. Record is the same as [Get Contact](#get-contact). 'jim-new-address@his-site.com', 'ipAddress' => $_SERVER['REMOTE_ADDR'], -); +]; // Create new a contact of ID 1 is not found? $createIfNotFound = true; @@ -454,22 +456,22 @@ Same as [Get Contact](#get-contact). ```php 1, 'firstname' => 'Jim', 'lastname' => 'Contact', 'email' => 'jim@his-site.com', 'ipAddress' => $_SERVER['REMOTE_ADDR'] - ), - array( + ], + [ 'id' => 1, 'firstname' => 'John', 'lastname' => 'Doe', 'email' => 'john@his-site.com', 'ipAddress' => $_SERVER['REMOTE_ADDR'] - ) -); + ] +]; $contact = $contactApi->editBatch($data); ``` @@ -534,7 +536,7 @@ Same as [Get Contact](#get-contact). ### Delete Batch Contact ```php deleteBatch($data); ``` Delete contacts. @@ -594,6 +596,7 @@ Same as [Get Contact](#get-contact). ### Remove from Do Not Contact ```php removeDnc($contactId, $channel); ``` @@ -619,7 +622,7 @@ Same as [Get Contact](#get-contact). ```php 'apicampaign', 'utm_source' => 'fb', 'utm_medium' => 'social', @@ -631,7 +634,7 @@ $data = array( 'query' => ['cid'=>'abc','cond'=>'new'], // or as string with "cid=abc&cond=new" 'remotehost' => 'example.com', 'lastActive' => '2017-01-17T00:30:08+00:00' - ); +]; $contactApi->addUtm($contactId, $data); ``` @@ -691,10 +694,10 @@ Same as [Get Contact](#get-contact) without the removed UTM Tags. ```php 'Score via api', 'actionName' => 'Adding', - ); +]; $contactApi->addPoints($contactId, $pointDelta, $data); ``` @@ -726,10 +729,10 @@ actionName|Name of the action ```php 'Score via api', 'actionname' => 'Subtracting', - ); +]; $contactApi->subtractPoints($contactId, $pointDelta, $data); ``` Subtract contact points From 81825b211732fceca56aa87e1ad180de785259a1 Mon Sep 17 00:00:00 2001 From: John Linhart Date: Thu, 19 May 2022 10:22:13 +0200 Subject: [PATCH 2/3] Batch api error examples provided --- source/includes/_api_endpoint_contacts.md | 34 +++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/source/includes/_api_endpoint_contacts.md b/source/includes/_api_endpoint_contacts.md index 5d05ab00b39..e502fadffbd 100644 --- a/source/includes/_api_endpoint_contacts.md +++ b/source/includes/_api_endpoint_contacts.md @@ -513,6 +513,40 @@ Contacts array. Record same as [Get Contact](#get-contact). > Note: In order to remove tag from contact add minus `-` before it. > For example: `tags: ['one', '-two']` - sending this in request body will add tag `one` and remove tag `two` from contact. +### Batch create/update error examples + +#### Maximum batch size limit + +The batch size limit is configurable with the `api_batch_max_limit` option. The default batch limit is 200 contacts per request. It can be changed in the `app/console/local.php` file. Increasing it may lead to timeouts so make sure you test your setup under heavy load before you increase this option. The response code in this case is `500 Internal Server Error`. + +```json +{"errors":[{"code":500,"message":"A max of 200 entities are supported at a time.","details":[]}]} +``` + +#### Validation error + +In case some of the contacts in the batch have invalid values then the overall response code will be `HTTP/1.1 201 Created` so you'll have to check for the response code for each contact separately in the response. In this example there were 2 contacts sent and one of them had invalid email address. The key in the error JSON object equals the key in the request starting from zero. In the example response the key is `"1"` which means the secod contact had invalid email address. + +_Note: Make sure you are not sending multiple contacts with the same unique identifiers (email address by default) in one batch request. Those contacts will get merged into one and then the response key may not match the request key because the response will have less contacts to return._ + +```json +{ + "contacts": [ + "[here is the array of contacts that were successfully saved. Replaced by this message to save space]" + ], + "errors": { + "1": { + "code": 400, + "message": "email: A valid email is required.", + "details": { + "email": ["A valid email is required."] + }, + "type": null + } + } +} +``` + ### Delete Contact ```php Date: Thu, 19 May 2022 10:25:36 +0200 Subject: [PATCH 3/3] HTTP version is not relevant --- source/includes/_api_endpoint_contacts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/_api_endpoint_contacts.md b/source/includes/_api_endpoint_contacts.md index e502fadffbd..4127e14ca7c 100644 --- a/source/includes/_api_endpoint_contacts.md +++ b/source/includes/_api_endpoint_contacts.md @@ -525,7 +525,7 @@ The batch size limit is configurable with the `api_batch_max_limit` option. The #### Validation error -In case some of the contacts in the batch have invalid values then the overall response code will be `HTTP/1.1 201 Created` so you'll have to check for the response code for each contact separately in the response. In this example there were 2 contacts sent and one of them had invalid email address. The key in the error JSON object equals the key in the request starting from zero. In the example response the key is `"1"` which means the secod contact had invalid email address. +In case some of the contacts in the batch have invalid values then the overall response code will be `201 Created` so you'll have to check for the response code for each contact separately in the response. In this example there were 2 contacts sent and one of them had invalid email address. The key in the error JSON object equals the key in the request starting from zero. In the example response the key is `"1"` which means the secod contact had invalid email address. _Note: Make sure you are not sending multiple contacts with the same unique identifiers (email address by default) in one batch request. Those contacts will get merged into one and then the response key may not match the request key because the response will have less contacts to return._