Developer Documentation

Integrating dStor into your application consists of a few simple steps.

1. Creating an API Key (Optional)

2. Using your dStor account login credentials OR using the API key to acquire a temporary access token

3. Attaching the temporary access token to upload request

The purpose of using the temporary access token model is to reduce reads to the dStor database, thereby ensuring that the system is able to remain performant even with a large number of users and dapps uploading content

Creating API Keys

In the dStor dashboard, click on the "Account" tab:

Now click the "Add" button to the top-right of the "Developer API Keys" table:

This will bring up a form where you will set a description of what the API key will be used for, and set a date when you would like the API key to expire. Then press the "Add" button:

The new API key, with its description and expiration, should now show up in your "Developer API Keys" table. In the "key" column you will see a truncated version of the API key. Click the copy icon next to the key in order to add the key to your clipboard for later use:

Acquire Temporary Access Token with API Key

To acquire a temporary token with an API key, send a GET request to the following endpoint: https://api.dstor.cloud/v1​/dev​/temp-token

You will need to add the following as headers:

"x-api-key": "your-dev-api-key" // required
"x-expiration": 1664349827 // optional, defaults to one year

As a curl command it would look like the following:

curl --location --request GET 'http://api.dstor.cloud/v1/dev/temp-token' \
--header 'api-key: my-dev-api-key'

The response should look like the following:

{
    "access_token": "eyJhbsomebiglongstring9.eyJkIjpmYWxzZSwibyI6ZmFsc2UsInMiOmZhbHNlLCJ0IjpudWxsLCJpYXQiOjE2MzI3ODg4MzcsImV4cCI6MTYzMjc5MjQzNywiYXVkIjoiZHN0b3IuY2xvdWQiLCJpc3MiOiJkc3Rvci5jbG91ZCIsInN1YiI6ImIyZTI3ODE3LTA0MzktNDViZC04YTNkLTVjNTk2MTg1YmQwNSJ9.PyKa8sILa7nyD-4eI4lA0xjFBPcncNZQL4_iclZ_Fs8"
}

This temporary access token is what you will attach to your uploads to get new content hosted on dStor.

Acquire a Temporary Access Token with Login Credentials

As an alternative to the API key form, you can request a temporary access token by using your normal dStor login credentials by sending a POST request to the following endpoint: https://api.dstor.cloud/​v1​/dev​/temp-token

The body of the request should look like the following:

{
  "email": "[e-mail]",
  "password": "string"
}

If your login credentials are correct, you should receive a response that looks like the following:

{
    "access_token": "eyJhbsomebiglongstring9.eyJkIjpmYWxzZSwibyI6ZmFsc2UsInMiOmZhbHNlLCJ0IjpudWxsLCJpYXQiOjE2MzI3ODg4MzcsImV4cCI6MTYzMjc5MjQzNywiYXVkIjoiZHN0b3IuY2xvdWQiLCJpc3MiOiJkc3Rvci5jbG91ZCIsInN1YiI6ImIyZTI3ODE3LTA0MzktNDViZC04YTNkLTVjNTk2MTg1YmQwNSJ9.PyKa8sILa7nyD-4eI4lA0xjFBPcncNZQL4_iclZ_Fs8"
}

Again, this temporary access token will be attached to our upload requests in order to host new files to the dStor network

Uploading a File to dStor

Now that you have received your temporary access token, we will use it to upload a file to dStor. We will be sending a POST request to the following endpoint:

https://api/dstor.cloud/api/v0/add

The following headers are optional. If you do not specify which folder to upload to, the API will upload it to your root folder:

"x-dstor-parent-id": number // ID of containing folder
"x-dstor-folder-path": string // path of containing folder
"x-dstor-comment": string // optional, useful for metadata purposes

Please note that only the parent folder ID OR path is required, do not include both.

Additionally, you will need to set the Authorization as a bearer token with the temporary access token that you received in the previous section.

Naturally, your file should be uploaded as form data, so that your complete upload request should look something like the following:

curl

curl --location --request POST 'https://api.dstor.cloud/api/v0/add' \
--header 'x-dstor-parent-id: 0' \
--header 'Authorization: Bearer eyJhbGciOiJSomeAccessTokenR5cCI6IkpXVCJ9.eyJkIjpmYWxzZSwibyI6ZmFsc2UsInMiOmZhbHNlLCJ0IjpudWxsLCJpYXQiOjE2MzI3OTI2NzUsImV4cCI6MTYzMjc5NjI3NSwiYXVkIjoiZHN0b3IuY2xvdWQiLCJpc3MiOiJkc3Rvci5jbG91ZCIsInN1YiI6ImIyZTI3ODE3LTA0MzktNDViZC04YTNkLTVjNTk2MTg1YmQwNSJ9.hVflWAvdw-jO2x_C_xvBcvAnXHusT8MpMZrzMs_7R_g' \
--form '=@"/Users/SomeUser/Documents/hello-world.txt"'

Javascript

var myHeaders = new Headers();
myHeaders.append("x-dstor-parent-id", "0");
myHeaders.append("Authorization", "Bearer eyJhSomeAccessToken1NiIsInR5cCI6IkpXVCJ9.eyJkIjpmYWxzZSwibyI6ZmFsc2UsInMiOmZhbHNlLCJ0IjpudWxsLCJpYXQiOjE2MzI3OTI2NzUsImV4cCI6MTYzMjc5NjI3NSwiYXVkIjoiZHN0b3IuY2xvdWQiLCJpc3MiOiJkc3Rvci5jbG91ZCIsInN1YiI6ImIyZTI3ODE3LTA0MzktNDViZC04YTNkLTVjNTk2MTg1YmQwNSJ9.hVflWAvdw-jO2x_C_xvBcvAnXHusT8MpMZrzMs_7R_g");

var formdata = new FormData();
formdata.append("", fileInput.files[0], "hello-world.txt");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: formdata,
  redirect: 'follow'
};

fetch("https://api.dstor.cloud/api/v0/add", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

NodeJS

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'api.dstor.cloud',
  'path': '/api/v0/add',
  'headers': {
    'x-dstor-parent-id': '0',
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkIjpmYWxzZSwibyI6ZmFsc2UsInMiOmZhbHNlLCJ0IjpudWxsLCJpYXQiOjE2MzI3OTI2NzUsImV4cCI6MTYzMjc5NjI3NSwiYXVkIjoiZHN0b3IuY2xvdWQiLCJpc3MiOiJkc3Rvci5jbG91ZCIsInN1YiI6ImIyZTI3ODE3LTA0MzktNDViZC04YTNkLTVjNTk2MTg1YmQwNSJ9.hVflWAvdw-jO2x_C_xvBcvAnXHusT8MpMZrzMs_7R_g'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = "------WebKitFormBoundary7MA4YWxkTrZu0gW\r\nContent-Disposition: form-data; name=\"\"; filename=\"hello-world.txt\"\r\nContent-Type: \"{Insert_File_Content_Type}\"\r\n\r\n" + fs.readFileSync('/Users/kylan/Desktop/hello-world.txt') + "\r\n------WebKitFormBoundary7MA4YWxkTrZu0gW--";

req.setHeader('content-type', 'multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW');

req.write(postData);

req.end();

The response object will look something like the following:

{
    "Name": "hello-world.txt",
    "Hash": "QmXEJJGbyMVa3jJ9iBATY8D1udATD7m6H7kVV7WoRgUEaT",
    "Size": "25136"
}

The hash property, specifically, is what you will use in your app to access the file. If the upload was successful then you should see the file show up in your dashboard within a few seconds: