File API - Introduction

[#1]

The File API allows you to download or upload files directly from YouServe, over HTTPS using the tool of your choice.

• Introduction
• Overview
• Concepts
• Encryption & Communication
• Authentication
• Tenant Authorization
• File Type Authorization
• Supported File Types
• Retention Period
• Curl Example
• Getting started
• Create Sandbox Application
• Get Access Token
• Send request to File API Endpoint including the access token
• Authentication Error Response
• File API Endpoints
• Request headers and responses
• Request headers
• Response codes
• Usage Limits
• Policy
• Spike arrest details

 

Introduction

Overview

Concepts

The File API is intended to upload and download files from system to system in a secure way. Files can be uploaded to and downloaded from the YouServe domain.

Files can be uploaded or downloaded with authorized apps, specified for a specified tenant, for specified business type(s).

A publisher app to upload files, a subscriber app to download files:

Explanation of  concepts 

Concept	Description
File API	Public endpoint to upload/list/download the files. In the request to File API, client id, business type id and tenant id are being identified. Once the files are uploaded to File API by a publisher application, the authorized subscriber application can list, download and delete the files.
Business Type/File type	The files which are related to the same “business” are functionally grouped in File types called “Business types”. File types are represented by an integer called “Business type id”.
Client Application	Client Applications are the users of the system. They are identified by a client Id. Client Applications are also authorized to tenantId(s). Client application needs to obtain a authentication token by using credentials (client id and client secret).The token includes client id, tenant id and the scopes of the application. Client Applications could be authorized either as publisher or subscriber of a business type.
Publisher	Publisher is a Client Application that can upload files of authorized business types and authorized tenants. The uploaded files can also be listed/downloaded.
Subscriber	Subscriber is a Client Application that can list/download/delete the files of authorized business types and authorized tenants.
Tenant	HR Core Client. Tenants are represented by tenant ids.

 

Encryption & Communication

File API is running on the Azure Cloud and has a microservice architecture to provide the best availability to the customers.

The communication between microservices which form File API system, is restricted by an internal token.

Https is the main communication protocol for external and internal communication. Database communication protocol is TLS 1.2.

File content is stored in Azure Storage and automatically encrypted when it is persisted to the cloud. Similarly all the databases are encrypted by Azure database encryption.

Authentication

We follow current industry standards and best practices. Authentication/authorization is not an exception. As part of the Identity and Access Management Strategy for system-to-system integrations, the File API is based on OAuth 2.0 and the authorization grant Client Credentials. Every API consumer system will be provisioned in our API Gateway as a Client Application (App). Client ID and Client Secret will be provided to be used by Apps as credentials. Thus, Apps will be able then to authenticate and get an access token (JWT) within the response payload. Subsequent requests authorization will be based on that access token previously retrieved.

Tenant Authorization

Client Applications (apps) need to be authorized to the corresponding Tenant (HR Core Client) in order to consume the API. By default, the applications are authorized to TenantId: sandbox.

File Type Authorization

Client applications (apps) need to be authorized as publisher or subscriber of business types

By default, sandbox apps are authorized to the Sandbox File Types.

Supported File Types

The File API has been designed to support a specific set of use cases. This may be extended over time, based on customer feedback. See the supported File Types.

Retention Period

The files will be physically deleted from Storage automatically after the retention period expires (1 month).

The metadata of the files (FileName, tenantId , BusinessTypeId, etc) is deleted after 6 months.

Curl Example

Here is an example of downloading a file using curl, available on most operating systems:

curl.exe https://api.youserve.nl/fileapi/v1.0/files/%fileid%?role=subscriber ^
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ^
--header "x-raet-tenant-id: 1234567" ^
--header "Accept: application/octet-stream"  ^
--output @C:/Youserve/somefile.xml

See complete examples for curl (Batch) and .Net in Github.

Getting started

Create Sandbox Application

1. Create account in the YouServe developer portal

YouServe developer portal

2. Create new File API Sandbox App

3. Retrieve credentials (Api Key, Secret key)

Get Access Token

1. Send request to Authentication API

The Authentication API is used to obtain the required access token. The request must include the content type header and the HTTP body must include the required Client Credentials.

curl -X POST 
 'https://api.youserve.nl/authentication/token'
 -H 'Cache-Control: no-cache' 
 -H 'Content-Type: application/x-www-form-urlencoded' 
 -d 'client_secret=xxxxxxx&client_id=xxxxxxxx&grant_type=client_credentials'

Below, a response example containing the access token and the expiration time which is 2 hours. After that time Apps need to re-authenticate to get a new access token.

{
    'access_token':'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'token_type': 'BearerToken',
    'expires_in': '7200',
}

Send request to File API Endpoint including the access token

App must use the Authorization header containing the access token. The API always operates within the scope of one HR Core client, also called tenant. An API call cannot retrieve data from multiple tenants.

By default, sandbox apps are authorized to the Sandbox File Types:

Business Type Id	Name	Authorization
7100	File API Sandbox Uploads	Publisher
7101	File API Sandbox Downloads	Subscriber

Below, a request example for listing sandbox files:

curl -X GET 
 'https://api.youserve.nl/fileapi/v1.0/files/%fileid%?role=subscriber' 
 -H 'Cache-Control: no-cache' 
 -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
 -H 'x-raet-tenant-Id: sandbox'

Authentication Error Response

The error payload shown below, describes the 401 error response Apps will receive in case of any authentication error.

{
    'message': 'Authentication Error',
    'correlationId': 'rrt-0d027480041e2a148-a-de-7885-572449-1',
    'issuedAt': '2018-03-27T07:44:25.554Z',
    'errorCode': 'unauthorized',
    'statusCode': 401
}

Miss use reasons for having authentication errors are:

• Wrong credentials
• Expired credentials
• Unauthorized access tokens
• Expired access tokens

For more detailed information please refer to the request headers & responses section

File API Endpoints

Once you have a valid access token you can perform below actions as publisher of the file types:

• Upload
• List uploaded files
• Download uploaded files

As subscriber of the file types you can perform below actions:

• List Available Files
• Download
• Delete

In case you have any question or doubt during the integration, you can reach us through the Visma Developer Community in Slack. See our Support page for more information.

Request headers and responses

See below the request headers and response codes of File API.

Request headers

Header Name	Description
Content-Type	The content type of the resource in case the request has content in the body. Example: Content-Type:multipart/related;boundary=foo_bar_baz
Authorization	The information required for authentication
Accept	The Accept request-header can be used to specify the media types which are acceptable for the response. Example: Accept:application/octet-stream

Response codes

Type	Responses	Situation
Success Codes	200 OK	Synchronous read, update, and delete operations
201 Created	Synchronous create requests
202 Accepted	A-synchronous operations
204 No Content	Referring to non-existing entity (e.g. after delete)
Redirection Codes	304 Not Modified	Resource has not been modified.
308 Permanent redirect	Resource has permanently moved.
Invalid Request Errors	400 Bad request	Bad Request (e.g. validation errors)
401 Unauthorized	Not Authorized: Missing or invalid access token	Reasons for having authentication errors are:Wrong credentials, Expired credentials, Unauthorized access tokens, Expired access tokens
403 Forbidden	Not Authorized: Authenticated, but user has no access to the API
404 Not Found	Invalid URL: Item does not exist (anymore). The canonical identifier (collection/{canonical id}) cannot be found. Not Authorized: Authenticated, access to api, but user has no access to to the resource (data authorization). From a security standpoint we don’t expose the reason why the object could not be found because an attacker can use this to figure out the internals of our system.
409 Conflict	Concurrency problem: Record changed by another user
Server Errors	500 Internal server error	Server Error (e.g. database failure, event could not be send)
503 Service unavailable	Server Error (resource temporary not available)

Usage Limits

We apply usage limits to ensure the availability of our services to all parties interacting with YouServe. These usage limits depend on your subscription.

Policy

The following policies are determined per registered application:

Quota	Weekly	Daily	Continous
API calls	2 hours per day. 1000 API calls within the time window. 7 days per month	2 hours per day. 1000 API calls within the time window. 40 times per month	6000 API calls per day, allowing to retrieve changes every 15 seconds
Authentication calls	7 successful authentication calls per month	40 successful authentication calls per month	400 authentication calls per month
Concurrent rate-limiting (API calls in parallel)	1	1	3
Spike arrest policy (max number of API calls per minute)	100 calls per minute	100 calls per minute	100 calls per minute

Spike arrest details

Spike arrest is the way we protect against traffic spikes. Our APIs and backend can handle a certain amount of traffic, and the Spike Arrest policy smooths the traffic to the general amounts.

Spike Arrest’s behaviour differs from what you might expect to see from the literal per minute values.

Our default spike arrest is set to 100pm (100 requests per minute). That does not mean you can do 100 requests inside a 1-second. Spike Arrest smooths the number of full requests in a minute by dividing it into smaller intervals:

Per-minute rates get smoothed into full requests allowed in intervals of seconds.

For example, 100pm gets smoothed like this: 60 seconds (1 minute) / 100pm = 0.6-second intervals, or 1 request allowed every 0.6 seconds. A second request inside of 0.6 seconds will fail. Also, the 101st request within a minute will fail.

When you exceed the policy, the API will return response code ‘429 - Too many requests’ and you have to wait for the next time window.