Redgate Data Modeler

12 December 2022

New Vertabelo Feature: Document-Oriented Vertabelo API

Updated on: November 17, 2023

One of the signs of a decent SaaS solution is its public API. A good API helps users to incorporate some automation into an application.

Based on our experience in using other SaaS services, we have introduced a more document-oriented version of our public API. In this article, we will demonstrate how to use Vertabelo API to fetch a list of documents (models), SQL scripts, and data models in various formats.

Why do we call our API document-oriented? We believe that users should easily access their documents (models, SQL scripts) through the API, simply by copying its URL.

• Generating a Token
• Document Identification
• Accessing Data
• Download a Document Tree
• Download a Physical Data Model as XML
• Download a Physical Data Model as an SQL Script
• Download a Logical Data Model as XML
• Download an SQL Script
• Download a Migration Script
• Managing Document (Model) Sharing
• List users with document sharing
• Send invitations to other team members
• Cancel document sharing
• Import a Physical Data Model as XML
• Importing the physical model
• Importing the logical model
• Summary

Generating a Token

First of all, you have to enable access to the API. You’ll need to have at least an individual account or be a member of a company plan to do this.

1. Go to the My profile page.



2. In the left-hand menu, click on Settings.



3. Click on Enable API Access.



4. You’ll get a generated API token. This token will be used to identify you when you connect to the Vertabelo API.



Note: You may also disable API access here. You can enable it again to get a new token.

Document Identification

All documents are identified by their URL. The document list is identified by the URL https://my.vertabelo.com/drive, while each model has a unique URL; you can simply copy these as needed. Please see the images below.



The document tree URL



The URL of the physical model. The unique identifier of the model is “WCs…”

Accessing Data

Vertabelo’s document-oriented API functionality allows users to easily fetch:

1. Lists of models and SQL scripts as a document tree in the JSON format.
2. A physical data model as an XML file or a corresponding SQL result.
3. A logical data model as an XML file.
4. An SQL script.
5. A migration script.

Examples

All the following examples use the curl tool. We assumed there is a “$TOKEN” variable available, which stores the public token generated as described in an earlier section of this article. A “:” character in the user parameter (-u option) is intended.

You can use the following command to declare the “$TOKEN” variable:

1	export TOKEN="<token_value>"

Download a Document Tree

To fetch a document tree, we need to make a GET HTTPS request to https://my.vertabelo.com/drive with the following HTTP headers:

1. An accept header with a JSON mime type: Accept: application/json
2. An authorization header with a username equal to $TOKEN and an empty password, in the following format: Authorization: Basic (base64($TOKEN:))

Here is the corresponding curl example:

1	curl  -u "$TOKEN:" -H "Accept: application/json" https://my.vertabelo.com/drive