A multipart upload request allows you to send metadata along with the data to upload. Use this option if the data you send is small enough to upload again in its entirety if the connection fails.
To use multipart upload:
- Create a POST request to the method’s /files URI with the query parameter uploadType=multipart.
Example - POST request multipart
POST https://api.youserve.nl/fileapi/v1.0/files?uploadType=multipart
- Add the top-level HTTP header: Content-Type. Set to multipart/related, and include the boundary string you’re using to identify the different parts of the request
Example - Content-Type header
Content-Type: multipart/related; boundary=foo_bar_baz
- Create the body of the request. Format the body according to the multipart/related content type [RFC 2387], which contains two parts:
a) Metadata part. Must come first, and must have a Content-Type header set to application/json; charset=UTF-8. Add the file’s metadata to this part in JSON format. The required metadata fields are:
| Key |
Value |
| FileName |
[FileName] |
| BusinessTypeId |
[BusinessTypeId] |
Note: For security reasons, file names have some restrictions:
- Filenames should fulfil the following characters sets:
[a-z],[A-Z],[0-9],[-],[_],[.],[(],[)],[,],[$],[+],[`],[=],[']
- Malicious file extensions are not allowed
b) Media part. Must come second, and should contain the bytes of the files. Identify each part with a boundary delimiter. [RFC 2046] The boundary delimiter line is defined as a line consisting entirely of two hyphen characters (“-“, decimal value 45) followed by the boundary parameter value from the Content-Type header field, optional linear white-space, and a terminating CRLF. The boundary delimiter MUST occur at the beginning of a line and it is terminated by either the header fields for the next part and two additional CRLFs, or by two additional CRLFs, in case there are no header fields for the next part. Boundary delimiters must not appear within the encapsulated material, and must be no longer than 70 characters, not counting the two leading hyphens.
Example - Boundary delimiter for Metadata part:
--foo_bar_baz[CRLF]
Content-Type: application/json; charset=UTF-8[CRLF]
[CRLF]
Example - Boundary delimiter for Media part:
--foo_bar_baz[CRLF]
[CRLF]
The boundary delimiter line following the last body part is a distinguished delimiter that indicates that no further body parts will follow. Such a delimiter line is identical to the previous delimiter lines, with the addition of two more hyphens after the boundary parameter value.
Example - Boundary delimiter for last body part:
Example - Send a multipart upload request using the Sandbox File Type
POST/mft/v1.0/files
?uploadType=multipart HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Content-Type: multipart/related;boundary=foo_bar_baz
--foo_bar_baz
Content-Type: application/json; charset=UTF-8
{
"name":"TestFile.txt",
"businesstypeid":"7100"
}
--foo_bar_baz
This is a test file
--foo_bar_baz--
If the request succeeds, the server returns the HTTP 201 Created status code along with the file’s metadata:
Example - Response successful request
HTTP/1.1 201
Content-Type: application/json
{
"id": "7ff1b498-169d-4048-8459-78f7bd7905a3",
"name": "TestFile.txt",
"size": 19,
"creationDate": "2020-02-27T11:03:49.2033291Z",
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"numChunks": 1
}
If the request fails, the server returns the HTTP 400, indicating Bad request.
Example - Response failed request
HTTP/1.1 400
Content-Type: application/json
{
"CorrelationId": "rrt-06f2e934a3cbdb710-a-de-13067-4959526-1",
"Message": "Error reading body of request. Please, check all the boundaries of the request",
"ErrorCode": "400",
"Exception": null
}
This protocol allows you to resume an upload operation after a communication failure interrupts the flow of data. Use this option if you transfer large files or if the likelihood of a network interruption or some other transmission failure is high
Initiate a resumable upload session and upload the first chunk of file
To initiate a resumable upload session:
- Create a POST request to the method’s /files URI and add the query parameter uploadType=resumable.
Example - Initial Post Request Resumable
POST https://api.youserve.nl/fileapi/v1.0/files?uploadType=resumable
- Add the top-level HTTP header: Content-Type. Set to multipart/related, and include the boundary string you’re using to identify the different parts of the request.
Example - Content-Type header
Content-Type: multipart/related; boundary=foo_bar_baz
- Create the body of the request. Format the body according to the multipart/related content type [RFC 2387], which contains two parts:
a) Metadata part. Must come first, and must have a Content-Type header set to application/json; charset=UTF-8. Add the file’s metadata to this part in JSON format. The required metadata fields are:
| Key |
Value |
| FileName |
[FileName] |
| BusinessTypeId |
[BusinessTypeId] |
Note: For security reasons, file names have some restrictions:
- Filenames should fulfill the following characters sets:
[a-z],[A-Z],[0-9],[-],[_],[.],[(],[)],[,],[$],[+],[`],[=],[']
- Malicius file extensions are not allowed
b) Media part. Must come second, and should contain the first chunk data of the file.
Create chunks of a maximum of 9MB. It’s recommended to have chunks with the same size, except for the final chunk that completes the upload. The best performance using this method is achieved with chunks of 4mb.
Identify each part with a boundary delimiter. [RFC 2046] The boundary delimiter line is defined as a line consisting entirely of two hyphen characters (“-“, decimal value 45) followed by the boundary parameter value from the Content-Type header field, optional linear white-space, and a terminating CRLF.
The boundary delimiter MUST occur at the beginning of a line and it is terminated by either the header fields for the next part and two additional CRLFs, or by two additional CRLFs, in case there are no header fields for the next part.
Boundary delimiters must not appear within the encapsulated material, and must be no longer than 70 characters, not counting the two leading hyphens.
Example - Boundary delimiter for Metadata part:
--foo_bar_baz[CRLF]
Content-Type: application/json; charset=UTF-8[CRLF]
[CRLF]
Example - Boundary delimiter for Media part:
--foo_bar_baz[CRLF]
[CRLF]
The boundary delimiter line following the last body part is a distinguished delimiter that indicates that no further body parts will follow. Such a delimiter line is identical to the previous delimiter lines, with the addition of two more hyphens after the boundary parameter value.
Example - Boundary delimiter for last body part:
Example - Initiate a resumable upload session using the sandbox File Type
POST/mft/v1.0/files
?uploadType=resumable HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Content-Type: multipart/related;boundary=foo_bar_baz
--foo_bar_baz
Content-Type: application/json; charset=UTF-8
{
"name":"TestFile.txt",
"businesstypeid":"7100"
}
--foo_bar_baz
This is the first chunk of the file
--foo_bar_baz--
If the session initiation request succeeds, the response includes a 206 Partial ContentHTTP status code, along with the upload token. Copy and save the upload token, so you can use it for uploading the next chunks of the file.
Example - Successful Response of initial request
HTTP/1.1 206
Content-Type: application/json
{
"uploadToken": "4927b6ffb51445ee982237ab6e4b3b30"
}
Note: The upload token expires after one hour.
If the request fails, the server returns the HTTP 400, indicating Bad request.
Example - Response failed request
HTTP/1.1 400
Content-Type: application/json
{
"CorrelationId": "rrt-06f2e934a3cbdb710-a-de-13067-4959526-1",
"Message": "Error reading body of request. Please, check all the boundaries of the request",
"ErrorCode": "400",
"Exception": null
}
A few checks for mitigation:
- Setting the right boundary definition for multipart/form-data body. Be mindful of setting two consecutive dashes (for example, –foo_bar_baz–) to mark the end of the boundary within the body of the HTTP request and two additional CRLFs after the boundary delimiters.
- If you are using Azure Logic Apps, go to the Logic App Code View. Within the HTTP body definition, replace every \n with \r\n. This is the key for successful file upload with multipart/form-data HTTP request using Azure Logic Apps.
To upload the file in multiple chunks follow the steps:
- Create a PUT request to the method’s /files URI.
- Add the query parameter uploadType=resumable
- Add the query parameter uploadToken=[uploadToken]
- Add the query parameter position=[position]
Example - Request to upload next chunks of the file
Put v1.0/files
?uploadType=resumable
&uploadToken=[uploadToken]
&position=[position]
-
Add the chunk’s data to the request body. Create chunks of a maximum of 9MB. It’s recommended to have chunks with the same size, except for the final chunk that completes the upload.
-
Add the top-level HTTP header Content-Type. Set to application/octet-stream
-
Send the request, and process the response. If the upload request is interrupted, or if you receive a 5xx response, send the request again. If the request succeeds, the server responds with 206 Partial Content, along with the upload token.
-
Repeat steps 1 through 7 for each chunk that remains in the file. It’s possible to parallel the upload of the intermediate chunks. The last chunk needs to be sent at the end of the requests, to close the session once that you have received confirmation that the previous chunks have been stored successfully.
Example - Upload next chunks of the file. This example shows a request that sends the next bytes of the file, and uses the upload token obtained in the previous step:
PUT/mft/v1.0/files
?uploadType=resumable
&uploadToken=4927b6ffb51445ee982237ab6e4b3b30
&position=1 HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Content-Type: application/octet-stream
And this is the second chunk of the file
If the request succeeds, the server responds with 206 Partial Content
Example - Successful response of intermediate request
There are two ways to complete a resumable upload session:
a) Add the query parameter close=true in the last PUT request.
b) Send additional Post request without bytes.
To complete a resumable upload session in the last upload request follow the steps described in section: “Upload next chunks of the file” and
- Add the query parameter close=true
- Add the top-level HTTP header: Content-Type. Set to application/octet-stream
Example - Put Request to complete a resumable upload session
Put https://api.youserve.nl/fileapi/v1.0/files
?uploadType=resumable
&uploadToken=[uploadToken]
&position=[position]
&close=true
If the request succeeds, the server responds with 201 created, along with the metadata of the file.
Example - Complete a resumable upload session in the last upload request
PUT/fileapi/v1.0/files
?uploadType=resumable
&uploadToken=4927b6ffb51445ee982237ab6e4b3b30
&position=2
&close=true HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Content-Type: application/octet-stream
And this is the last chunk of the file
This example shows a request that sends the last bytes of the file, and complete the upload of the file, using the upload token obtained in the previous step:
If the request succeeds, the server responds with 201 Created, along with the metadata of the file.
Example - Successful response of final request
HTTP/1.1 201
Content-Type: application/json
{
"id": "7ff1b498-169d-4048-8459-78f7bd7905a3",
"name": "TestFile.txt",
"size": 78,
"creationDate": "2020-02-27T11:03:49.2033291Z",
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"numChunks": 2
}
To complete a resumable upload session sending an additional Post request without bytes, follow the steps:
- Create a POST request to the method’s /files URI.
- Add the query parameter uploadType=resumable
- Add the query parameter uploadToken=[uploadToken]
- Do not add the top-level HTTP header: Content-Type.
Example - Post Request to complete a resumable upload session
Post https://api.youserve.nl/fileapi/v1.0/files
?uploadType=resumable
&uploadToken=[uploadToken]
If the request succeeds, the server responds with 201 created, along with the metadata of the file.
Example - Complete a resumable upload session sending an additional Post request. This example shows a request that sends and additional Post request to complete the upload of the file, using the upload token obtained in the previous step:
Post/fileapi/v1.0/files
?uploadType=resumable
&uploadToken=4927b6ffb51445ee982237ab6e4b3b30 HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the server responds with 201 Created, along with the metadata of the file.
Example - Successful response of final request
HTTP/1.1 201
Content-Type: application/json
{
"id": "7ff1b498-169d-4048-8459-78f7bd7905a3",
"name": "TestFile.txt",
"size": 78,
"creationDate": "2020-02-27T11:03:49.2033291Z",
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"numChunks": 2
}
This endpoint allows you to retrieve a paginated collection of the files that have been uploaded by you.
In order to use the list endpoint:
- Create a Get request to the method’s /files URI and add the query parameter role=publisher
Example - List Uploaded Files
GET https://api.youserve.nl/fileapi/v1.0/files?role=publisher
| Parameter Name |
Value |
Description |
| pageIndex |
integer |
The number of the page. (Default:0) |
| pageSize |
integer |
The maximum number of files to return per page. Acceptable values are 1 to 1000, inclusive. (Default: 20) |
Example - List Uploaded Files. This example shows how to list the files that have been uploaded by you (role=publisher)
GET/fileapi/v1.0/files
?role=publisher
&pageSize=10
HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 200 OK HTTP status code, along with the paginated collection of the files that were uploaded by you.
By default, the paginated collection of files will be ordered by date descending.
Example - Response of List Uploaded Files
HTTP/1.1 200
Content-Type: application/json
{
"data": [
{
"fileId": "4a31f004-aab8-4419-9072-077c35074553",
"fileName": "TestFile1.txt",
"fileSize": 209715222,
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"publisherId": "1b604f7e-d40f-466d-b9b0-ddeb3945df14",
"uploadDate": "2021-01-10T21:05:41.937"
},
{
"fileId": "62777c81-e83f-4888-8202-cf35ea2ca38b",
"fileName": "TestFile2.txt",
"fileSize": 2048,
"tenantId": "sandbox",
"businessType": {
"id": 7100,
"name": "7100"
},
"publisherId": "1b604f7e-d40f-466d-b9b0-ddeb3945df14",
"uploadDate": "2021-01-10T08:07:41.113"
}
],
"pageIndex": 0,
"pageSize": 20,
"count": 2
}
To sort the files in an specific order, use the query string $orderBy
The format of the query string is: field modifier
Where:
- field specifies the key to sort. Valid keys are ‘uploadDate’, ‘businessType’, ‘fileName’.
- modifier specifies the order of the sorting (‘asc’ and ‘desc’)
Example usage:
By default, files are sorted by UploadDate desc.
Note: The order in which files need to be downloaded may depend on the type of data and the way the receiving system needs to process it. See examples below:
| What you want query |
Query String |
| Retrieve ‘RST Functie’ files (BT: 101002. Definition of all functions/positions available in Beaufort/YouForce). You would only need the latest file so you can ignore the rest, as each file contains the complete list of functions/positions. |
$filter=businessType eq 101002.
In this case, the $OrderBy query string is not needed, as files are sorted by UploadDate desc by default. |
| Retrieve employee mutations in Bint Harmony Files (BT: 101100). Based on the default settings that Beaufort/YouForce only exports the mutations instead of the full employee dataSet, it is important that you get all the new files and download them from old to new. |
$filter=businessType eq 101100&$orderBy=uploadDate asc |
This endpoint allows you to download the files that have been uploaded by you.
In order to use this download endpoint:
- Create a Get request to the method’s /files/[fileId] URI and add the query parameter role=publisher
- Add the HTTP header Accept=application/octet-stream
Example - Download Request
GET https://api.youserve.nl/fileapi/v1.0/files/[fileId]?role=publisher
Example - Download uploaded file. This example shows how to download a file that was uploaded by you using the Sandbox Tenant
GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=publisher
HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
If the request succeeds, the response includes a 200 OK HTTP status code, along with the bytes of the file.
Example - Successful response of Download uploaded File
HTTP/1.1 200
<root>
<company>Visma YouServe</company>
<product>File API</product>
<content>Sample File</content>
</root>
Visma Denemarken
Visma Finland
Visma Letland
Visma Nederland
Visma Noorwegen
Visma Zweden
Visma Developers & Partners
Visma Latijns-Amerika