Fine-Grained Permissions and Enhanced DoltHub API

August 11, 2023

4 min read

For those of you that are new, Dolt is a database that supports Git-style versioning. DoltHub is a place on the internet to share and collaborate on Dolt databases. We are excited to introduce a great enhancement to DoltHub, offering you enhanced control and flexibility when using DoltHub's APIs. In this blog post, we'll dive into the specifics of our new API token system, alongside the introduction of new API endpoints.

Fine-Grained API Token System

At DoltHub, we're dedicated to security. To enhance the level of security of our API, our new API token system grants control over permissions, database access, and scopes associated with your API tokens. For instance, you can now create a customized token designed solely to read pull requests within a specific database, ensuring the token's usage is confined without broader database access. For creating a token with full access like our previous API token, you can simply select all databases and scopes while granting write permissions.

Enhanced Security Through Database Control

The new system allows users or organizations to associate their API tokens with one or more databases which they have access to, providing a refined level of control over data exposure.

Define Token Scopes

A highlight is that users can accurately set the scope of their API tokens. Whether you're focusing on pull requests, branches, or other aspects of your projects, you can craft API tokens customized to your exact requirements. You can select from a variety of scopes to ensure your token accesses only the functionality needed for your tasks.

Permission Levels

Our system allows you to fine-tune permission levels for each token. Want to limit your token to listing pull requests or branches within a database? Simply assign read-only permission to your token.

Creating API Tokens

You can create an API token via the tokens section in your account settings

create a API token

Expanding API Endpoints

Alongside our new API Token System, we've also introduced a set of new API endpoints.You can refer to our API documentation for comprehensive details.

Here's a practical example of utilizing these API endpoints to interact with pull requests within the museum-collections database under the organization dolthub, including listing, viewing, and updating pull request.

Listing Pull Requests

To list pull requests, make a GET request to the {owner}/{database}/pulls endpoint using an authorization token. The response of pull request list is paginated, so you need to use the next page token included in the response to retrieve the following pages of pull requests.

import requests

url = 'https://www.dolthub.com/api/v1alpha1/dolthub/museum-collections/pulls'

headers = {
  'authorization': 'token YOUR_API_TOKEN'
  }

response = requests.get(url, headers=headers)

The JSON response:

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pulls": [
    {
      "pull_id": "20",
      "title:": "Added new data",
      "description:": "Added missing museums, sourced from museums.com",
      "state": "open",
      "created_at": "2023-07-06T18:00:00Z",
      "creator": "liuliu"
    },
    {
      "pull_id": "19",
      "title:": "MFA Boston collection",
      "description:": "Added data from the Boston ART Museum collection",
      "state": "merged",
      "created_at": "2023-07-02T23:10:02.703Z",
      "creator": "taylor"
    },
    {
      "pull_id": "18",
      "title:": "Add data from museums.eu",
      "description:": "Data from the European Museum Network",
      "state": "merged",
      "created_at": "2023-07-01T13:10:02.703Z",
      "creator": "dustin"
    }
  ],
  "next_page_token": "AWE2Nm9uMWQ23FSQ7oRTbCXYTLLvNDhNs5hIFebQFI66FW-SYXGSlh3XcUQ8zmtLQ00QgD0X5FZr5ZTAhvT2FfRrGog7OuUno9wdTIXFQpkkX0opYoJL6Vrn2emlXkMBTiZYMqChyhR92_Yxd58B0w5nMrfXFf8v7xfAkN46hw"
}

For the next page of pull requests, make a request to https://www.dolthub.com/api/v1alpha1/dolthub/museum-collections/pulls?pageToken=AWE2Nm9uMWQ23FSQ7oRTbCXYTLLvNDhNs5hIFebQFI66FW-SYXGSlh3XcUQ8zmtLQ00QgD0X5FZr5ZTAhvT2FfRrGog7OuUno9wdTIXFQpkkX0opYoJL6Vrn2emlXkMBTiZYMqChyhR92_Yxd58B0w5nMrfXFf8v7xfAkN46hw.

Get Pull Request details

To access detailed information about pull request #20, make a GET request to the {owner}/{database}/pulls/{pull_id} endpoint.

Here's how you can retrieve the specifics of pull request #20:

import requests

url = 'https://www.dolthub.com/api/v1alpha1/dolthub/museum-collections/pulls/20'

headers = {
  'authorization': 'token YOUR_API_TOKEN'
  }

response = requests.get(url, headers=headers)

A successful JSON response includes the pull request details:

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "pull_id": "20",
  "title:": "Added new data",
  "description:": "Added missing museums, sourced from museums.com",
  "state": "open",
  "from_branch_owner": "liuliu",
  "from_branch_database": "museum-collections",
  "from_branch_name": "feature",
  "to_branch_owner": "dolthub",
  "to_branch_database": "museum-collections",
  "to_branch_name": "main",
  "created_at": "2023-07-01T18:00:00Z",
  "author": "liuliu"
}

Updating A Pull Request

Given that the state of the pull request is open, let's proceed to close it. Use a PATCH request to the {owner}/{database}/pulls/{pull_id} endpoint to update the state of this pull request. This API enables modifications to the title, description, and state. Please note that only closing a pull request is supported via updating. Merging a pull request can be done by posting to the endpoint {owner}/{database}/pulls/{pull_id}/merge, while opening a pull request via the endpoint {owner}/{database}/pulls.

To close pull request #20 on the museum-collections database, include the state field in the request body.

import requests

url = 'https://www.dolthub.com/api/v1alpha1/dolthub/museum-collections/pulls/20'

headers = {
  'authorization': 'token YOUR_API_TOKEN'
  }

data ={
  "state": "closed"
}

response = requests.patch(url, headers=headers, json=data)