API integration: How to upload a file to Baserow using multipart/form-data

Baserow is a versatile no-code database platform that empowers users to create custom databases/applications, manage data, and collaborate effectively. One of its valuable features is the ability to upload files to specific rows, which enhances data organization and accessibility.

Imagine you are working on an application that uses the Baserow API, and you need to upload files via API. In this scenario, let’s say you want to upload a PDF file to a specific endpoint. Baserow is API-first and developer-friendly, so you can use the file field to upload files programmatically.

Multipart upload lets you upload a large file in smaller sections, called parts. These parts are like smaller pieces of the overall file. With a multipart upload request, you can upload metadata and data in the same request. You have the flexibility to upload these parts separately and in any sequence you want. This is particularly useful when working with APIs that require files to be sent as part of 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.

2. Now that the workspace is set up, you can either create a database from scratch or choose a template from our template library.

3. 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 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 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. Next, add the authentication credentials.

   Authorization: Token YOUR_DATABASE_TOKEN

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

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

   file	multipart The file multipart containing the file contents.

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

   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.

7. Click on the Send button to make the API request and get a response.

   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.

   

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.

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

Uploading files using multipart/form-data method can help you do amazing things when working with APIs. You can also incorporate it into forms where users can upload files easily. By following the steps above, you can easily understand how to send files using this method and feel more comfortable doing it. This will make your interaction with APIs smoother and more effective.

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 in 2023
• 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.