How to upload files using multipart/form data using the Baserow API

Baserow is a versatile platform that allows users to create custom databases and applications without code. It also enables effective data management and collaboration. One of its useful features is the ability to upload files to specific rows, which improves data organization and accessibility.

If you’re using the Baserow API for your application and need to upload files programmatically, you can use the file field. Baserow is API-first and developer-friendly, so it supports uploading files via API.

To upload a large file, you can use multipart upload. This allows you to break the file into smaller parts and upload them separately. With a multipart upload request, you can include both metadata and data in the same request. You have the flexibility to upload these parts separately and in any order you prefer. This is especially helpful when working with APIs that require files to be included in the request body.

What we’ll do

In this tutorial, we’ll walk you through the process of uploading a file to Baserow by using the multipart/form-data. We’ll cover the following steps:

• Access Baserow workspace and table
• Create a database token
• Reference the database API documentation
• Upload a file via POST request
• Test in Postman or Insomnia
• Create a file field
• Update an existing row

Prerequisites

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

• A Baserow hosted or self-hosted account.
• API testing tool like Postman or Insomnia.
• Access to a Baserow workspace and table with at least one row where you intend to upload files.
• Access to the Baserow API and the specific endpoint for file uploads.
• A file that you want to upload.

Let’s dive in!

Upload a file using multipart/form-data

1. Access Baserow workspace and table

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 workspace and adding a database to the workspace.

1. Navigate to the workspace where your target table resides or create a new workspace. To create a new workspace, simply click on the + Create workspace button. Then, click on Add workspace.

If you’re 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.

1. Now that the workspace is set up, you can either create a database from scratch or choose a template from our template library.
2. Next, add a new table or click on the desired table within the existing database to open it. A default table will be added to all newly created databases.

Now, let’s populate the Baserow database with data.

2. 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.

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.

3. Reference the 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.

Let’s take a look at the API documentation to figure out the right way to upload a file to Baserow using multipart/form-data.

4. Upload a file via POST request

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, 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" \\\\\\\\ \\\\\\\\
-F file=@photo.png
"<https://api.baserow.io/api/user-files/upload-file/>"

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’ll test the API. You should have the correct endpoint and the necessary authentication credentials before attempting to upload files or interact with Baserow API.

5. Test in Postman or Insomnia

You can test the file upload in Postman or Insomnia.

Insomnia is an open-source platform for API development. It helps you create and manage API requests, run automated tests, and collaborate with your team. Postman also lets you automate API tests by creating collections of requests and tests. These tools are great for repetitive, regression, and integration testing.

We’ll be using Insomnia to upload test files in this tutorial, but the same steps apply to any API that accepts file uploads.

1. Launch the Insomnia application, create a new request collection, then add a new HTTP request. Give your request a meaningful name, like "File upload to Baserow API.”
2. Select POST as the appropriate HTTP method for the request.
3. In the URL field, enter the API endpoint URL for file uploads retrieved from the database API documentation. For Baserow hosted cloud version, we’re using https://api.baserow.io/api/user-files/upload-file/
4. 
5. Next, add the authentication credentials.
6. Authorization: Token YOUR_DATABASE_TOKEN
7. Click on the Auth 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 created in the earlier step.
   • Add to = “Header”.
8. 
9. Add the file’s data to the request body. Click the Body tab below the URL field then choose “Multipart Form” as the type of data to send in the body of a request. A file multipart is expected to contain the file contents.

1. Add a name-value pair for the file.
   1. Click on “Add” to create a new name-value pair.
   2. In the “name” column, enter the name for the field that will receive the file as “file.”
   3. In the “value” column, click on the dropdown and select “File.”
   4. Click on Choose Files and select the file you want to upload.
2. 
3. The Content-Type: multipart/form-data header will be added automatically to help the server identify the media type of the request body that is present in this request.
4. Click on the Send button to make the API request and get a response.
5. That’s it! You should receive a response from the API indicating whether the upload was successful or not. If the request succeeds, the server returns the HTTP 200 OK status code along with the file’s metadata in the lower pane.
6. 

Now that we’ve sent the file using multipart/form-data, let’s go ahead and upload the file into the table.

6. Create a file field

Back in our Baserow table, 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 for 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.

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.

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 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.

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

Be cautious with uploaded files. Some files may have hidden vulnerabilities that could allow unauthorized access to your valuable data. Always verify the content before granting access. This is particularly important for images and files. Stay proactive in protecting 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

Using the multipart/form-data method for uploading files can be very useful when working with APIs. It allows you to do some really cool things and even integrate it into forms for easy file uploads by users. By following the steps outlined above, you can quickly grasp how to send files using this method and become more confident in doing so. This will ultimately make your interaction with APIs much smoother and more efficient.

Other useful resources

The following articles may also be helpful:

• API integration: How to upload files via URL
• Streamline collaboration and review process with database automation
• How to create an effective product roadmap
• Automate your workflow: Sync Google Sheets and Baserow with Zapier

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.