Import Document via CustomTranslator API in PHP - php

Question

I'm trying to import a TMX file via the Microsoft Custom Translator API in PHP. Unfortunately, I keep running into the following error:
"DocumentDetails must follow type IEnumerable[ImportDocumentRequestDetails]."
I've managed to make other (though only GET) requests to the API successfully, so it's specifically this request I'm having trouble figuring out.
So far, I've tried various permutations of the request, mostly by trial and error. I've tried replicating the request by uploading the same file in the portal, which succeeds without problems, but I've not been able to replicate this in PHP (7.3).
I've also tried to reverse-engineer the C# API samples on GitHub. Unfortunately, my C# knowledge isn't that sharp and I'm sure there are nuances I'm missing. I have noticed the sample uses a 'Language' string, whereas the portal seems to use a 'LanguageCode', as well as other inconsistencies which haven't made solving this much easier.
A stripped-down version of my code, with only the relevant parts (one can assume a valid access token and local filepath to a valid .tmx) is the following:
Class CustomTranslator {
private $curl;
private $aAccessToken; // valid, working token
// Set up connection and login with initial user
public function __construct() {
$this->curl = curl_init();
$aOptions = array(
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 60
);
curl_setopt_array($this->curl, $aOptions);
}
function ImportParallelDocument($strFilePath) {
$aRequestContent = [
'Files' => new CURLFile($strFilePath, mime_content_type($strFilePath), basename($strFilePath)),
'DocumentDetails' => [
'DocumentName' => basename($strFilePath),
'DocumentType' => 'training',
'IsParallel' => true,
'FileDetails' => [
'Name' => $strFilePath,
'Language' => 'Dutch',
'Type' => pathinfo($strFilePath, PATHINFO_EXTENSION),
'OverwriteIfExists' => true
]
]
];
return $this->Request("v1.0/documents/import?workspaceId=".CUSTOMTRANSLATOR_WORKSPACEID, $aRequestContent, 'POST');
}
// Prototype request function
private function Request($strRequest, $aData = array(), $strMethod = 'GET') {
$strRequest = CUSTOMTRANSLATOR_API_URL.$strRequest;
// Reset between requests
curl_setopt($this->curl, CURLOPT_POST, false);
curl_setopt($this->curl, CURLOPT_HTTPHEADER, ['Authorization: Bearer '.$this->aAccessToken['access_token']]);
if(isset($aData['authorization'])) $aData['authorization'] = $this->aAccessToken['access_token'];
if ($strMethod == 'GET') {
$strRequest .= "?".http_build_query($aData);
}
else {
curl_setopt($this->curl, CURLOPT_POST, true);
curl_setopt($this->curl, CURLOPT_HTTPHEADER, ['Authorization: Bearer '.$this->aAccessToken['access_token'],
'X-HTTP-Method-Override: '.$strMethod]);
curl_setopt($this->curl, CURLOPT_POSTFIELDS, $aData);
}
curl_setopt($this->curl, CURLOPT_URL, $strRequest);
$strResponse = curl_exec($this->curl);
// Return the JSON array if it can be decoded, otherwise the actual curl response
return json_decode($strResponse, true)?:$strResponse;
}
}
As stated, when I try to upload a file using the above code, the exact error I'm receiving is {"message":"DocumentDetails must follow type IEnumerable[ImportDocumentRequestDetails].","display":false}, unfortunately without further specification of what's missing or incorrect. I'm hoping to achieve a successful file import of a TMX file which does successfully import via the portal itself, which I understand implements the same API.
I expect I'm simply missing something, or doing something not quite right, so any help would be appreciated!

Answer 1

With help from a colleague, figured out a will-do-for-now workaround, by simply providing the equivalent JSON of the call as it's used in the portal:
$aRequestContent = [
'Files' => new CURLFile($strFilePath, mime_content_type($strFilePath), basename($strFilePath)),
'DocumentDetails' =>
'[{ "DocumentName": "",
"DocumentType": "training",
"FileDetails": [{
"Name": "'.basename($strFilePath).'",
"LanguageCode": "en",
"OverwriteIfExists": true }]
}]'
];
It's not the best solution, but for the purposes of a preview API, it'll work for now (until it inevitably ends up in production, sigh).
Examining the JSON a little closer led me to discover the nested array structure (presumably for multi-file uploads), which wasn't inherently obvious to me at first. However, the following array structure is sufficient for requests to be processed:
$aDocumentDetails = [[ // Note the nested array here, for index numbering
'DocumentName' => '',
'DocumentType' => ucfirst($strType),
'FileDetails' => [[ // As well as here
'Name' => basename($strFilePath),
'LanguageCode' => $strLanguageCode,
'OverwriteIfExists' => $bOverwrite
]]
]];
$aRequestContent = [
'Files' => new CURLFile($strFilePath, mime_content_type($strFilePath), basename($strFilePath)),
'DocumentDetails' => json_encode($aDocumentDetails)
];
In short, the API expects DocumentDetails (and FileDetails) in indexed sub-arrays:
[0 => [ 'DocumentName' => ...,
'FileDetails' => [0 => ['Name' => ...]
];
Understanding this tidbit helped me tremendously.