tutorials
Back to overview

API integration: How to upload files via URL

Baserow API: How to upload files via URL

Making file sharing and transfers smooth is important when it comes to exchanging information. Luckily, there’s a handy way to do this: upload a file via API by directly retrieving it from a URL.

Sharing data becomes much easier when you retrieve files directly from their source location on the web. This eliminates the need for manual downloads and uploads. Instead of downloading a file and then uploading it, you can simply upload it directly from a URL.

This not only saves time but also makes collaboration a breeze, especially when you’re dealing with large files or trying to merge data from different online sources. It’s like getting the job done in a single streamlined move, making the whole process much quicker and easier.

What we’ll do

In this tutorial, we’ll upload a file by directly downloading them from a given URL and creating a row with this file. We’ll cover the following steps:

Prerequisites

To complete this tutorial, you’ll need the following:

  • A Baserow hosted or self-hosted account.
  • Basic familiarity with Baserow.
  • API testing tool like Postman or Insomnia.

Let’s dive in!

Upload a file to Baserow from a URL

1. Set up a Baserow database

Log in to your existing Baserow account or create a new account if you don’t have one already.

Once you log in, you can access the dashboard to add workspaces and databases. Let’s start by creating a new workspace or adding a database to an existing workspace.

To create a new workspace, simply click on the + Create workspace button. Then, click on Add workspace to get started.

If you are just starting with Baserow, we recommend you read our support article on how to create a workspace and how to add collaborators to your workspace.

Now that the workspace is set up, let’s create a database. You can either create a database from scratch or choose a template from our template library.

For this tutorial, we’ll walk you through the process of creating a database from scratch.

  1. Click on the + Create new button to add a new database to the workspace.
  2. Select the “Database” option from the dropdown modal.
  3. Give the database a descriptive name.

A default table will be added to the newly-created database. Now, let’s populate the Baserow database with some data.

Set up a Baserow database

2. Create a file field

Let’s create a file field in the table.

To add a new field,

  1. Click on the + button located just after the last visible field.
  2. When prompted to select a field type, choose the “File” field as the desired field type.
  3. Give the new field a descriptive name that makes sense to you. This could be something like “Uploaded file,” “Attachment,” or a name relevant to the kind of files users will be uploading.
  4. Once you’ve configured the field settings, click on the Create button to finalize the process and save your changes.

Baserow is API-first and developer-friendly, so you can use this file field to upload files programmatically. You can also incorporate it into forms where users can upload files easily.

Once the field is created, you can further customize it and access additional options from the field’s dropdown menu. To edit an existing field, click on the dropdown arrow next to its name, and the field configuration menu will open up for you to make changes.

3. Create a database token

Baserow makes authentication easy and secure for seamless integration with third-party applications.

To access Baserow data externally, we’ll need to generate at least one database token. These tokens can grant specific permissions to create, read, update, and delete data up to the table level.

To generate a database token, follow these steps:

  1. Access your profile and then click on Settings.
  2. Click on the Database tokens tab.
  3. Click on the Create token + button.
  4. Input a name and choose the workspace.
  5. Click on the Create token button to generate a new database token for the workspace, which will be authorized for your user account.

Create a database token

We will use the database token to access the endpoints provided in the database documentation. It’s only possible to use the endpoints if the database token has read, create, or update permissions.

4. Reference database API documentation

The rules and functions to follow in order to make an API call are laid out in the database documentation. Understanding this will help efficiently manage data retrieval and manipulations through the API.

REST APIs are core operational tools that enable organizations and developers to consume and build on top of Baserow’s various database capabilities. Baserow’s API follows REST semantics, uses JSON to encode objects, and relies on standard HTTP codes, and machine and human-readable errors to signal operation outcomes.

To access the database API documentation,

  1. Click on the vertical ellipsis beside the database.
  2. Select View API Docs from the menu.

The database API consists of different endpoints for specific actions. The endpoints can be found in the left sidebar.

Reference Baserow database API documentation

Let’s take a look at the API documentation to figure out the right way to upload a file to Baserow by downloading it from the provided URL.

5. Upload a file from a URL

Baserow file field accepts an array of objects containing at least the name of the user file. You can use the “File uploads” endpoints to upload the file. To upload a file via URL, a POST request will be made to the endpoint.

Here is an example of what the request looks like:

curl \
-X POST \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
-H "Content-Type: application/json" \
"https://api.baserow.io/api/user-files/upload-via-url/" \
--data '{
    "url": "https://baserow.io/assets/photo.png"
}'

The response for this operation:

{
    "url": "https://files.baserow.io/user_files/VXotniBOVm8tbstZkKsMKbj2Qg7KmPvn_39d354a76abe56baaf569ad87d0333f58ee4bf3eed368e3b9dc736fd18b09dfd.png",
    "thumbnails": {
        "tiny": {
            "url": "https://files.baserow.io/media/thumbnails/tiny/VXotniBOVm8tbstZkKsMKbj2Qg7KmPvn_39d354a76abe56baaf569ad87d0333f58ee4bf3eed368e3b9dc736fd18b09dfd.png",
            "width": 21,
            "height": 21
        },
        "small": {
            "url": "https://files.baserow.io/media/thumbnails/small/VXotniBOVm8tbstZkKsMKbj2Qg7KmPvn_39d354a76abe56baaf569ad87d0333f58ee4bf3eed368e3b9dc736fd18b09dfd.png",
            "width": 48,
            "height": 48
        }
    },
    "name": "VXotniBOVm8tbstZkKsMKbj2Qg7KmPvn_39d354a76abe56baaf569ad87d0333f58ee4bf3eed368e3b9dc736fd18b09dfd.png",
    "size": 229940,
    "mime_type": "image/png",
    "is_image": true,
    "image_width": 1280,
    "image_height": 585,
    "uploaded_at": "2020-11-17T12:16:10.035234+00:00"
}

Next, we will test the API.

6. Test API

You can test the API using Postman or Insomnia.

Insomnia is a collaborative open-source API development platform that allows you to create and manage API requests, write and run automated tests, and collaborate with team members. Postman also allows you to automate your API tests by creating collections of requests and tests. These tools are useful for performing repetitive tests, regression testing, and integration testing.

We’ll be using Postman for this tutorial.

Copy the URL of the file you want to upload, which usually directs us to where the file is stored online.

In Postman, create an API request.

  1. Select POST method, then input the Request URL retrieved from the database API documentation. For Baserow hosted cloud version: https://api.baserow.io/api/user-files/upload-via-url/

    In Postman, create a Baserow API request

  2. Next, add the authorization and authentication data.

    Authorization: Token YOUR_DATABASE_TOKEN

    Click on the Authorization tab then select API Key as the Authorization type. Input the following values:

    • Key = “Authorization”.
    • Value = “Token YOUR_DATABASE_TOKEN”. Replace YOUR_DATABASE_TOKEN with the token retrieved in the earlier step.
    • Add to = “Header”.

    add the authorization and authentication data

  3. Use the HTTP Content-Type header on the request to set the proper content. The Content-Type header is added to help the server identify the media type of the request body that is present in this request.

    Content-Type: application/json

  4. Add the file’s data to the request body. To upload a file, you’ll need a direct URL to the file. Make sure your file is hosted online and accessible via a URL. Paste the URL of the file you want to upload.

    {
        "url": "https://baserow-media.ams3.digitaloceanspaces.com/pagedown-uploads/91ee1040-161b-48aa-9418-1ec75322840e/Untitled.png"
    }
    
  5. Click Send. If the request succeeds, the server returns the HTTP 200 OK status code along with the file’s metadata in the lower pane.

Save the Request and add it to your Postman collection. You can import the Postman collections to pull in similar requests.

Upload file to a Baserow row

7. Update an existing row

The response can then be used to update an existing row in the table. The accepted body fields depend on the fields that the table has. Because we created the file field in Step 2 above, we can upload the file to the corresponding row.

The file field accepts an array containing objects with the name of the file. The response contains an array of more detailed objects related to the files.

{
    "field_12": [
        {
            "visible_name": "string",
            "name": "string"
        }
    ],
}

The numbers/ids are for example purposes, the field_ID must be replaced with the actual id of the field or the name of the field if user_field_names is provided.

Then, pass the details from the upload response.

visible_name string
A visually editable name for the field.
name string
Accepts the name of the already uploaded user file.

Once initiated, Baserow will start the upload process. The system will retrieve the file from the provided URL and associate it with the selected row.

Once the upload is complete, the cell will display the name of the uploaded file or an appropriate indicator.

Note that not all uploaded files are as harmless as they may appear. Certain uploads might contain vulnerabilities that provide unauthorized visitors with a gateway to valuable data. It’s important to verify all content before granting access to your data. This is especially important for elements like images or files. Stay proactive in safeguarding your platform’s integrity.

Your Baserow database token serves as a digital key, granting authorized users access to the database’s resources while ensuring data integrity and privacy.

Summary

As tech continues to evolve, this approach shows us that even tiny changes can greatly impact how we handle our online tasks. Making uploads smoother by grabbing files from a given URL is like upgrading how we move data. This boosts how fast things get done, cuts out extra hassles, and makes teamwork better.

Instead of downloading files to your device and then uploading them to your desired location, this enhances efficiency by skipping the need to save files on your device before uploading. This streamlines the process, making it quicker and more convenient.

Other useful resources

In case you’ve run into an issue while following the tutorial, feel free to reach out to ask for help in the Baserow community.

Want to write a new article for Baserow or contribute to an existing one? Check out our contribution guidelines for writing articles.

release
September 12, 2023 by Bram Wiepjes
Release 1.20

Baserow version 1.20 comes with email notifications, workspace level audit log, search for calendar view, new shortcuts, context menu improvements, and more.

info
January 26, 2023 by Georgina Brisk
Best Airtable alternatives
no-code
January 10, 2023 by Olivier Maes
No-Code Platforms in 2023
Want to contribute?

Want to write a post in collaboration with us?

How to contribute?