REST API reference

Our REST API try to adhere to common REST principles. You will find verbs and status codes have the same meaning as they do else where. This API allow you to make commit, listing repositories, reading data from commits and more. We also made a JavaScript SDK for convenience if you use our API in the browser.

Authentication

We allow authentication via API key. You can get one at API key settings page. API key should be included in Authorization header for each request like this: Authorization: APIKEY <your key here>. Note that API keys do not expire on their own (but you can remove them any time) and allow you to do everything so keep them a secret!

HTTP status codes

For successful requests, status code 2XX is returned. 4xx status codes indicate there is a problem with the request. Status code 500 indicate there's an error with WRGL's server (which should be rare).

WRGL return these status codes

Code Description
200 OK Successful operation.
400 Bad Request There is an issue with how the request is formed.
401 Unauthorized There's a lack of or faulty credentials from user.
403 Forbidden You are not allowed to carry out this operation.
404 Not Found This resource or one of the resources this operation depends on cannot be found.
500 Internal Server Error An internal server error.

Error response

If an 4XX status code is returned then the response will contain the error message.

Example error response:

{
  "message": "repo name cannot be empty"
}

List repositories

List all repositories. A maximum of 30 repos are returned for each request. Subsequent requests can use offset query parameter to fetch more repos.

Query parameters Type Description
offset number Offset at which to fetch repos. If left empty fetch from the beginning.
search string If not empty, return repos with this prefix.
Response fields Type Description
repos array of repo objects
count number Total count of repositories that can be returned.

Repo object

Fields Type Description
name string The repo name. Can only consist of lowercase alphanumeric characters, hyphen and underscore. It also must begin with an alphabet letter and is at least 2 characters long.
hash string Its latest commit hash. Use this to access the latest commit.
updateTime string Timestamp of latest commit. e.g. 2020-12-31T23:59:60Z
isPublic boolean Indicate whether this repo and all of its content is publicly accessible.
size number Total size in bytes of this repo.

Create commit

Create a new commit along with the repo if it does not already exist. If the repo already exist, append commit to this repo.

Request must be in multipart/form-data format.

Request fields Type Description
repoName string Name of repository.
message string Commit's purpose in plain English.
csv.primaryKey string Comma-separated list of columns included in primary key. e.g. "product_id,year". Note that the order of these columns matters. A different order denote a completely different primary key. If left empty then all columns are included in the primary key.
csv.dataFile file The CSV file gzipped. Note that rows with the same primary key will be deduplicated.
Response fields Type Description
hash string Hash of resulting commit. This is how you refer to this commit.
contentHash string Hash of underlying CSV. If 2 commits has the same content hash then there's no need to compare them.

List commits

List commits under a repo starting with the most recent. This will always return at most 20 commits in a single request. Each successful response will return the next page token which you can use to request the next page.

Query paramaters Type Description
pageToken string If empty fetch the first page. If not empty, fetch from the position indicated by this string.
Response fields Type Description
commits array of commit objects.
nextPageToken string Use this as the pageToken query param in the next request to fetch the next page. If it is "EOF" then it means there's no more page to fetch. Needless to say try to list commits with pageToken=EOF will return an error.

Commit object

Fields Type Description
hash string The commit hash.
message string Commit's purpose on plain English.
commitTime string Commit's timestamp.
prevCommitHash string Previous commit's hash. Empty if this is the first commit in repo.
authorId string Commit author id.
authorUsername string Commit author username.
authorAvatarUrl string Commit author avatar url.

Get latest commit

Get the latest commit from a repository.

Query parameters Type Description
getContent string If set to "true" then return extra information about the underlying table (CSV content in a commit is referred to as table).
Response fields Type Description
hash string The commit hash.
message string Commit's purpose on plain English.
commitTime string Commit's timestamp.
prevCommitHash string Previous commit's hash. Empty if this is the first commit in repo.
contentHash string Hash of underlying CSV.
table table object This field will be populated if getContent=true is present in query parameters. Contains extra information about the CSV.
authorId string Commit author id.
authorUsername string Commit author username.
authorAvatarUrl string Commit author avatar url.

Table object

Fields Type Description
columns array of strings List of all column names.
numRows number Number of rows in CSV. Note that rows with the same primary key are deduplicated.
primaryKey array of strings List of all columns included in primary key.

Get commit with hash

Get commit with specified hash. It has the same query paramters and response as latest commit request

Download CSV

Download the original CSV file.

This endpoint support HTTP range requests so you can pull the file in bits and pieces rather than whole.

Publish repository

Publishing a repository makes all of its commits publicly accessible. Whereas private repo is only accessible by you. Only paid plans have the ability to make repo private.

Request body must be in JSON format:

Request fields Type Description
public boolean Indicate whether this repo is publicly accessible.

Response fields are the same as latest commit response.