Using the Smartabase API

This article about using the Smartabase API is aimed at technical users and software engineers.

The Smartabase API facilitates the input and output of your Smartabase data. It allows you to view the configuration of the event and profile forms on your Smartabase site, as well as perform some basic administrative tasks like creating new user accounts. You can configure webhooks to notify you about updated data and form configurations.

This article provides an overview of the Smartabase API and its capabilities, including the following topics:

• Prerequisites.

• Documentation and getting started.

• Development and testing.

• Performance considerations: using webhooks vs. polling.

Prerequisites

Before you can begin using the Smartabase API, specific settings must be enabled for your Smartabase site. Please contact your Smartabase consultant for more information.

To use the API, you will need a Smartabase account with the appropriate roles and groups for the data that you are authorized to access. Your Smartabase administrator can assist with setting this up.

You will need the following details:

• Username and password for your Smartabase account.

• The URL of your Smartabase site (e.g. https://example.smartabase.com/site).

• The version of your Smartabase instance, which can be found in the footer of the login screen (e.g. Version 6.12.6 shown in the screenshot below).

Documentation and getting started

Documentation is available upon request and, depending on the version of the endpoints (newer or older), comes either online or as a PDF file. We also have some Postman collections available. The documentation provides the specification for the API as well as code examples.

We are going through a transition to the new version of our API, which is why the information below is broken up into sections about newer and older endpoints.

Using newer endpoints

Please contact your Smartabase consultant to gain access to docs.smartabase.dev. The documentation will tell you how to authenticate and what you need to include in headers. Note that you will use a username and password to create a session for all subsequent API requests. The data is transmitted in JSON format.

We are planning to support OAuth2.0 authentication in the future.

Using older endpoints

Please contact your Smartabase consultant to request the documentation and required .proto file. Older endpoints use basic authorization for each request, and data is transmitted in protobuf format. To use it, you will need to:

1. Download protobuf for your language and confirm that it’s working by following the tutorial.

2. Use protoc (or the equivalent) and the supplied .proto file to generate the classes for your language.

Over time, we will transition old API features to the newer version of the API and then deprecate them.

Development and testing

We highly recommend you begin using the Smartabase API with test data and accounts that do not belong to real people. This will reduce the risk of adding any incorrect data to someone’s account, deleting data by mistake or causing unnecessary load on your Smartabase site. Your Smartabase administrator will be able to set this up.

Further, you may wish to evaluate your use of the API on a separate instance of Smartabase reserved for development and testing. If you would like to look into this option, please contact your Smartabase consultant.

Performance considerations: using webhooks vs. polling

While you could poll Smartabase for changes, it is not efficient and can impact performance. For data that is updated frequently, we recommend configuring webhooks that will let you keep track of the creation of new user accounts, changes to event forms and new records added to Smartabase. Webhooks are configured using the API.