Tutorial: Integrating dStor Into Your App

Intro

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

1. Creating an API key (optional)

   • The API key is a token that the user can use to get a Access Token which will allow your application be able to interact with the dStor API.

   • Users can add multiple API keys as needed, as well as remove them.

   • API Keys should be treated with care and never exposed to ensure account security.

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

3. Attaching the temporary token to upload requests

   • 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 applications uploading content.

Creating API Keys

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

Change image to new UI

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

Change image to new UI

This opens a modal for you to 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. The default is 365 days but can be set to expire sooner or later depending on your particular security needs. 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:

Swap API Key for an Access Token

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:

In order to access the file you will simply navigate to the following endpoint, with the has attached to the end:

https://api.dstor.cloud/ipfs/QmTjVD1pXDacjCdyEsiaBT5pJ78v2z2XTFHVQxiPEgRAze

Congratulations, you have uploaded your content to dStor!