API

DoltHub provides an API for accessing Dolt databases via web requests. A Dolt database can be attached to a DoltHub remote (see below for details) and pushed. At that point DoltHub provides an API against which users can execute Dolt SQL with results returned as JSON. Let's turn again to our example repository, dolthub/ip-to-country. Let's use the Python requests library to explore it in the Python console:

import requests
owner, repo = 'dolthub', 'ip-to-country'
res = requests.get('https://dolthub.com/api/v1alpha1/{}/{}'.format(owner, repo))
res.json()

This shows our repository metadata as a dictionary:

{'query_execution_status': 'Success',
'query_execution_message': '',
'repository_owner': 'dolthub',
'repository_name': 'ip-to-country',
'commit_ref': 'master',
'sql_query': 'SHOW TABLES;',
'schema': [{'columnName': 'Table',
'columnType': 'String',
'isPrimaryKey': False}],
'rows': [{'Table': 'IPv4ToCountry'}, {'Table': 'IPv6ToCountry'}]}

We can now execute the same sample query we used in our web example:

query = '''SELECT * FROM IPv4ToCountry WHERE CountryCode2Letter = "AU"'''
res = requests.get('https://www.dolthub.com/api/v1alpha1/{}/{}/{}'.format(owner, repo, branch), params={'q': query})
res.json()

This yields the results as JSON, with both schema and data:

{'query_execution_status': 'RowLimit',
'query_execution_message': '',
'repository_owner': 'dolthub',
'repository_name': 'ip-to-country',
'commit_ref': 'master',
'sql_query': 'SELECT * FROM IPv4ToCountry WHERE CountryCode2Letter = "AU"',
'schema': [{'columnName': 'IPFrom',
'columnType': 'Int',
'isPrimaryKey': False},
{'columnName': 'IpTo', 'columnType': 'Int', 'isPrimaryKey': False},
{'columnName': 'Registry', 'columnType': 'String', 'isPrimaryKey': False},
{'columnName': 'AssignedDate', 'columnType': 'Int', 'isPrimaryKey': False},
{'columnName': 'CountryCode2Letter',
'columnType': 'String',
'isPrimaryKey': False},
{'columnName': 'CountryCode3Letter',
'columnType': 'String',
'isPrimaryKey': False},
{'columnName': 'Country', 'columnType': 'String', 'isPrimaryKey': False}],
'rows': [{'IPFrom': '16777216',
'IpTo': '16777471',
'Registry': 'apnic',
'AssignedDate': '1313020800',
'CountryCode2Letter': 'AU',
'CountryCode3Letter': 'AUS',
'Country': 'Australia'},
.
.
.

As a reminder, this API is in Alpha version, and we do not currently support authentication for private repositories. We will continue to flesh this out, as well as improve query performance, over time.

Edit on GitHub