UiBhelp's public knowledge cards

KI 3742 New feature: data transfer via SAFE File API

(updated )
An overview of what the SAFE File API is, and how it is used for import and export of data for SAFE servers.
What is the SAFE File API?

The SAFE File API is a REST-based interface that sits between the SAFE server and your local machine. By using an external tool, you can communicate with the API’s endpoints to transfer data into and out of the SAFE server. This solution significantly reduces data transfer times compared to the previous method. Note, however, that both data transfer methods will remain available for the foreseeable future.

It is important to understand that SAFE File API is not a tool in itself, but rather a means of communicating with the SAFE servers. Below, we explain how to use such tools and how to utilize the API for importing and exporting data.

Requirements for using SAFE File API
  • You must be an existing SAFE user with access to import and/or export functions.
  • You must have specific access to SAFE File API. If you do not have this access, please request it via a ticket to UiB Help, including your username and server name.
  • You must have access to and be connected to the UiB SAFE VPN. Further details on this can be found here: KI 0407 Connecting to a SAFE server.
  • You must have a program or tool capable of communicating with the endpoints defined in SAFE File API. You are free to choose whichever tool you prefer; however, we recommend using NORTRE CLI, which we developed ourselves. We also provide a guide on how to use this command-line tool for imports and exports: KI 3743 New SAFE tool: import/export with NORTRE CLI.

General guide for using SAFE File API

Note: This is a general guide on how to communicate with the endpoints, applicable to any tool you choose to use.
If this seems difficult to understand, we provide more details on the recommended tool, NORTRE CLI, here: KI 3743 New SAFE tool: import/export with NORTRE CLI.
It may be easier to follow a step-by-step guide on how to use a specific tool, as the way different tools function can vary.
Furthermore, NORTRE CLI has been designed specifically with the SAFE File API in mind.

Once you have connected to the SAFE VPN and have your communication tool ready, you will interact with specific endpoints.
Get access token

First we need an access token to demonstrate that we have the authorization to send requests to the other endpoints.This endpoint is protected by a UiB login. You must paste the address into your web browser and then log in.

Example photo of UiB login on the browser.

After authentication you will receive a access token in your web browser.

Example photo of successful authentication and access token response.

In this example, the key has been obscured by a black box, but typically it will appear as a long string of letters and numbers. You need to copy this string and enter it into your chosen tool.

The exact process varies depending on the tool. In some cases, you look for an "auth" or "bearer token" field where you can paste the value. In other cases, you include it as part of the request itself when calling other endpoints. It is recommended to consult the documentation for your specific tool regarding how to handle access tokens.

Important: This token is only valid for 1 hour. After that you will need to repeat this step to obtain a new token.

Importing

Once you have obtained an access token (as described above), you can import files to the SAFE server from your local PC. This is not done via a web browser, as was the case when obtaining the token, but rather through your chosen communication tool. Do not be confused by the fact that the endpoints appear clickable or are highlighted in blue throughout the rest of the article, this just happens automatically. Also remember to keep the UiB SAFE VPN enabled throughout the process.
  • General endpoint for import: POST https://api.safe.uib.no/v1/files/import

In addition, your request must follow a specific structure, including certain parameters.
  1. Headers
Headers are metadata required to make an HTTP request to an endpoint.
For communication with the SAFE File API import endpoint, we require:
  • A `Content-Type` header with the value "multipart/form-data".
    This is usually set automatically by your tool when sending a request, so you generally do not need to worry about it.
  • An `Authorization` header using the "bearer token" format. The value should be the key (token) you obtained earlier.

       2. Body

The body contains the actual content sent with the request. In this case, it consists solely of the file you wish to import.
  • A "file" field, with the file content as its value.
To reference the file, you typically just provide the filename, including its file extension.
For example: "blabla.txt"

When using a terminal, you may not be in the same directory as the file you wish to import. In such cases, you must specify both the file path and the filename.
For example: "C:\Users\username\Documents\blabla.txt"


       3. Query Parameters

Query parameters are appended directly after the endpoint.
For communication with the SAFE File API import endpoint, we require:
  • A "filename" parameter (a string/text value).
    This allows you to specify a new name and file extension for the imported file within the SAFE server.
    Typically, you simply use the same filename here as you specified in the body.
    For example: "filename=blabla.txt".
  • A "server" parameter (a string/text value).
    Here, you specify the SAFE server to which you wish to import the file(s).
    For example: "server=safemachine-name"
Example including both parameters: POST https://api.safe.uib.no/v1/files/import?filename=blabla_newname.txt&server=safemachine-name
  • Full generic example:
tool -X POST "https://api.safe.uib.no/v1/files/import?filename=blabla_newname.txt&server=safemachine-name" \
         -H "Authorization: Bearer 12ASXDF3oigyXuyxef123ff3jh4" \
         -o "file=@C:\Users\username\Documents\blabla.txt"

An actual token key will be much longer than the example shown above.
Also, please remember again that each tool has different formatting and variables.
  • More on importing:
After importing, the file(s) will appear in the import folder on the selected SAFE server. Specifically, it is the folder named safe_file_api_import, provided you have import access.

Note: Files you import into the SAFE server are accessible only to you on the server. No one else can view them until you move them to a shared area. The import will fail if the file is not found or is empty. You will also receive an error message if the filename already exists in the import folder on the SAFE server.

Exporting

Just as with importing, once you have obtained an access token, you can export files from the SAFE machine to your local PC. Do not be confused by the fact that the endpoints appear clickable or are highlighted in blue throughout the rest of the article, this just happens automatically. Also remember to keep the UiB SAFE VPN active during the process.
  • General endpoint for exporting: GET https://api.safe.uib.no/v1/files/export

You must also structure your request to include these parameters:
  1. Headers
Headers are metadata required to make an HTTP request to an endpoint.
For communication with the SAFE File API export endpoint, we require:
  • Authorization using the "bearer token" format. The value should be the acess token you obtained earlier.

     2. Query Parameters

Query parameters are added directly after the endpoint.
For communication with the SAFE File API export endpoint, we require:
  • The "filename" parameter (a string/text value).
    This specifies which file should be exported from the SAFE server.
    Note that the file must first be placed in the `safe_file_api_export` folder.
    Example: "filename=blabla.txt".

  • The "server" parameter (a string/text value).
    This specifies the SAFE server from which you wish to export the file(s).
    Example: "server=safemachine-name".
Example including both parameters: GET https://api.safe.uib.no/v1/files/export?filename=blabla.txt&server=safemachine-name
  • Full generic example:
```
tool -X GET "https://api.safe.uib.no/v1/files/export?filename=blabla.txt&server=safemachine-name" \
               -H "Authorization: Bearer 12ASXDF3oigyXuyxef123ff3jh4" \
               -o "C:\Users\username\Downloads\blabla.txt"
```

We have included an additional parameter here ( -o ) to demonstrate that the tool you are using may have a function for saving the file to a specific location on your PC, rather than just retrieving the content directly.
An actual token key will be much longer than the example shown above.
Also, please remember again that each tool has different formatting and variables.

Additional information
  • Although the access token is only valid for 1 hour, file transfers will not be cancelled if the data transfer has already begun. This applies only to new requests.
  • You can import and export files of up to 950 GB at a time. However, please note that larger files will take longer to import or export.
  • There is a 1-day timeout, meaning that if a file transfer takes longer than 24 hours, it will be cancelled.
Please let us know if you encounter any issues or if you believe this document should be updated.