Mijn Communities
Help

File API - Downloading files (Subscriber)

21-04-2023 17:20 (Bijgewerkt op 21-04-2023)
  • 0 Antwoorden
  • 0 kudos
  • 2881 Weergaven

 

Subscribers

Subscriber is a Client Application that can list/download/delete the files of authorized business types and authorized tenants.

 

File list of available files

This endpoint allows you to retrieve a paginated collection of the files that have been delivered to you.
 

In order to use this list endpoint:

  • Create a Get request to the method’s /files URI and add the query parameter role=subscriber

Example - List Available Files

GET https://api.youserve.nl/fileapi/v1.0/files?role=subscriber

Optional Parameters

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)
$filter string A query for filtering the file results. See the “Search for files” guide for the supported syntax.
$orderBy string A query for sorting the file results. See the “Sort files” guide for the supported syntax.

 

Example - List Available Files. This example shows how to list the files that have been delivered to you. (role=subscriber) using the sandbox tenant

GET/fileapi/v1.0/files
?role=subscriber
&pageSize=20
&$filter=businessType eq 8000
&$orderBy=uploadDate desc
HTTP/1.1

Host: api.youserve.com
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 are available for you.

By default, only available files are shown. (Not downloaded files). In this case, the “count” field will return the total number of available files considering the query string specified in the parameter $filter. When a file is downloaded, it will not be shown by default anymore in the list, and the “count” field will be decreased to reflect the currently available files.

 

Example - Response of List Available Files

HTTP/1.1 200
Content-Type: application/json

{
    "data": [
        {
            "downloaded": false,
            "fileId": "d92ffb21-7938-488b-a405-bcbc9e0a9696",
            "fileName": "sandbox_test_file.xml",
            "fileSize": 107,
            "tenantId": "sandbox",
            "businessType": {
                "id": 7101,
                "name": "7101"
        },
            "publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
            "uploadDate": "2021-03-25T07:30:23.657Z"
        },
        {
            "downloaded": false,
            "fileId": "c5d7438e-5c29-47e7-b518-01e5a39d6711",
            "fileName": "sandbox_test_file.txt",
            "fileSize": 33,
            "tenantId": "sandbox",
            "businessType": {
                "id": 7101,
                "name": "7101"
        },
            "publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
            "uploadDate": "2021-03-25T07:30:23.657Z"
        },
        {
            "downloaded": false,
            "fileId": "f0d109df-b933-44f9-92d7-cca525ef120a",
            "fileName": "sandbox_test_file.csv",
            "fileSize": 76,
            "tenantId": "sandbox",
            "businessType": {
                "id": 7101,
                "name": "7101"
        },
            "publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917",
            "uploadDate": "2021-03-25T07:30:23.657Z"
        }
    ],
    "pageIndex": 0,
    "pageSize": 20,
    "count": 3
}

 

 

Search for files

To search for a specific set of files, use the query string $filter to filter the files to return.
 

The format of the query string is: field operator values

Where:

  • field specifies the field to search upon.

  • operator specifies the condition for the field.

  • values are the specific values you want to use to filter your search results.

Field Description Values
uploadDate Upload Date according to DateTime OData format <DateTime>
businessType Business Type ID <BusinessTypeId>
status Status 'available', 'downloaded', 'all'
fileName Name of the file <FileName>
Operator Description
gt Great than
lt Less than
ge Great than or equal
le Less than or equal
eq Equal
ne Not equal
and And
or Or
( Open Parenthesis
) Close Parenthesis
startsWith parameter starts with the following substring (only for FileName)
endsWith parameter ends with the following substring (only for FileName)
contains parameter contains the following substring (only for FileName)

Query string examples

What you want to query Query String
Files greater than 2020-05-19T08:42:47.400Z uploadDate gt 2020-05-19T08:42:47.400Z
Files greater than 2020-05-19T08:42:47.400Z and lesser than 2020-05-19T16:42:47.400Z uploadDate gt 2020-05-19T08:42:47.400Z and uploadDate lt 2020-05-19T16:42:47.400Z
All Files (downloaded and available) status eq 'all'
Downloaded Files status eq 'downloaded'
Available Files status eq 'available'
Files related to BusinessTypeID 7101 businessType eq 7101
Files related to BusinessTypeID 7100 or 7101 businessType eq 7100 or businessType eq 7101
Downloaded Files related to BusinessTypeID 7100 or 7101 status eq 'downloaded' and (businessType eq 7100 or businessType eq 7101)
All Files greater than 2020-05-19T08:42:47.400Z related to BusinessTypeID 7101 uploadDate gt 2020-05-19T08:42:47.400Z and businessType eq 7101 and status eq 'all'
All files with a name that starts with “payroll” startsWith(FileName, 'payroll')
All files with a name that ends with “holidays“ endsWith(FileName, 'holidays')
All files with a name that contains “test“ contains(fileName, 'test')
All files with a name that starts with “payroll“ and a BusinessTypeId 7101 startsWith(FileName, 'payroll') and businessType eq 7101

 

 

 

Sort files

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’, ‘status’, ‘fileName’.
  • modifier specifies the order of the sorting (‘asc’ and ‘desc’)

Example usage:

?$orderBy=uploadDate asc

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:

Query string examples

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

 

 

 

File download

There are two types of downloads you can perform:

 

Download complete file

This endpoint allows you to download the files that have been delivered to 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=subscriber

  • Add the HTTP header Accept=application/octet-stream

Example - Download Request

GET https://api.youserve.nl/fileapi/v1.0/files/[fileId]?role=subscriber

Example - Download Available File. This example shows how to download a file that was delivered to you

GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
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 Available File

HTTP/1.1 200

<root>

<company>Visma YouServe</company>

<product>File API</product>

<content>Sample File</content>

</root> 

 

 

Download file by chunks

These endpoints allow you to download chunks of files that have been delivered to you.
 

In order to download files by chunks you need to use these endpoints:

  • Retrieve file size with a Head request

  • Retrieve chunks of the file.

Retrieve file size

File API allows you to download chunks of files that have been delivered to you. This endpoint will be used to check if this capability is in place for the resource.

  • Create a Head request to the method’s /files/[fileId] URI and add the query parameter role=subscriber

Example - Check Available File can be downloaded by chunks

HEAD/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
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 headers:

  • Content-Length with the size of the requested file
  • Accept-Ranges with the range unit accepted

Example - Successful response of Check Available File can be downloaded by chunks

HTTP/1.1 200

Content-Length:107

Accept-Ranges:bytes

 

Retrieve chunks of a file

File API allows you to download chunks of files that have been delivered to you.

  • Create a Get request to the method’s /files/[fileId] URI and add the query parameter role=subscriber
  • Add the HTTP header Accept: application/octet-stream
  • Add the HTTP header Range: bytes=firstByte-lastByte where firstByte is the first byte of the chunk you want to download and lastByte is the last one.

Example - Download first 50 bytes of an Available File. This example shows how to download a chunk of a file that was delivered to you

GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
Range: bytes=0-49

If the request succeeds, the response includes a 206 Partial Content HTTP status code, along with the bytes of the chunk and the headers:

  • Content-Range with the range retrieved and total file size
  • Content-Disposition with the value attachment; filename=name of the file

Example - Successful response of Download first 1024 bytes of an Available File

HTTP/1.1 206
Content-Length: 50
Content-Range: bytes 0-49/107
Content-Disposition:attachment; filename=sandbox_test_file.xml
<root>
<company>Visma YouServe</company>
<product>Fi
 
Not satisfiable range

When the lower limit of the range is bigger than the last byte of the file, the request will retrieve a 416 error. Example - Request not satisfiable range when Download Range out of Available File bounds

GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
Accept: application/octet-stream
Range: bytes=107-110

The response includes a 416 Range Not Satisfiable HTTP status code, along with the header:

  • Content-Range with the accepted range unit and the file size

Example - Response - Error not satisfiable range when Download Range out of Available File bounds

HTTP/1.1 206
Content-Range: bytes */107
{
    "correlationId": null,
    "message": "Range not satisfiable.",
    "errorCode": "416",
    "exception": null
}

 

 

File delete

This endpoint allows to delete a file you are subscribed to. This will not delete the file for everyone, just for the app that is requesting it.

In order to use this endpoint:

  • Create a Delete request to the method’s /files/[fileId] URI and add the query parameter role=subscriber
  • Add the HTTP header Accept=application/octet-stream

Example - Delete File

DELETE https://api.youserve.nl/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696
?role=subscriber
HTTP/1.1
Host: api.youserve.nl
x-raet-tenant-id: sandbox
Authorization: Bearer xxxxxxxxx
If the request succeeds, the response includes a 204 No Content HTTP status code.

If the request succeeds, the response includes a 204 No Content HTTP status code.

Example - Response of Delete File

HTTP/1.1 204

 

 

Medewerkers