Document database

This article provides a hands-on tutorial for the aedifion.io document database. After this tutorial, you will be able to

• check your available and used quota,
• upload a file,
• list all files,
• download a file, and
• delete a file.

Preliminaries¶

The examples provided in this article partly build on each other. For the sake of brevity, boiler plate code such as imports or variable definitions is only shown once and left out in subsequent examples.

To execute the examples provided in this tutorial, the following is needed:

• A valid login (username and password) to the aedifion.io platform.
• A project with access to the document database enabled.
• A working installation of Python or Curl.

Access and quotas¶

The document database is available and accessible per company and per project. Each company and project is assigned a quota that depends on your aedifion.io license and is fixed at the time of order. You can query the document database quota for your company or your project through the following endpoints:

• GET /v2/company/quota (query company quota)
• GET /v2/project/{project_id}/quota (query project quota)

Both endpoints accept the following parameters:

Example request

We request the quota for the files service which is the service upon which the document database is realized.

GET /v2/company/quota?service=files
host: https://api.aedifion.io
accept: application/json

Example response

The response is a JSON-parseable object that contains the quota limits, how much we have used up of it and what remains available.

HTTP/1.1 200
content-type: application/json

{
  "files": {
    "quota_available": {
      "files": 2000,
      "space_bytes": 2000000000
    },
    "quota_limits": {
      "file_size_bytes": 50000000,
      "files": 2000,
      "space_bytes": 2000000000
    },
    "quota_used": {
      "files": 0,
      "space_bytes": 0
    }
  }
}

From the above response, we learn:

• We have an overall available quota of 2000000000 bytes (2 GB) and 2000 files where a single file must not be larger than 50 MB (quota_limits).
• We haven't made any use of our quota (quota_used) and it is hence still available in the full (quota_availble).

Let's make some use of our quota and upload our first file.

Uploading a file¶

You can upload files to your company or project space using the following endpoints:

• POST /v2/company/file (upload to company space)
• POST /v2/project/{project_id}/file (upload to project space)

Both endpoints accept the following parameters:

Example request:

We upload a new file EDE-bacnet.pdf to the subfolder EDE/.

POST /v2/company/file?folder=EDE%2F
host: https://api.demo.aedifion.io
accept: application/json

file: (binary)

Example response:

As before, the response is a JSON-parsable object that tells if the upload was successful and returns the newly created path. Note that the HTTP status code 201 indicates that a new resource was created.

HTTP/1.1 201
content-type: application/json

{
  "resource": {
    "path": "EDE/EDE-bacnet.pdf"
  },
  "success": true
}

Executing this example request a second time leads to an error because the file already exists as the response clearly indicates:

HTTP/1.1 400
content-type: application/json

{
  "error": "File 'EDE/EDE-bacnet.pdf' already exists.",
  "success": false
} 

Now that we have uploaded a file, let's view the list of files in our document database.

Listing files¶

Existing files can be queried with the following endpoints:

• GET /v2/company/files (files in company space)
• GET /v2/project/{project_id}/files (files in project space)

Both endpoints accept the following parameters that allow us to fine-tune the retrieved list:

Example request

We query files which match the search term bacnet and select the first results page and limit it to 100 items.

GET /v2/company/files?search=bacnet&page=1&per_page=100
host: https://api.aedifion.io
accept: application/json

Example response

The response is a JSON as requested. items lists the single file EDE/EDE-bacnet.pdf that we have uploaded before together with its creation date and size in bytes. The meta object provides pagination information that is useful to frontends and apps.

HTTP/1.1 200
content-type: application/json

{
  "items": [
    {
      "last_modified": "2020-09-25 12:44:26.906000+00:00",
      "path": "EDE/EDE-bacnet.pdf",
      "size_bytes": 5348640
    }
  ],
  "meta": {
    "current_page": 1,
    "items_per_page": 100,
    "total_items": 1,
    "total_pages": 1
  }
}

Now that we have uploaded and listed files, let's download a file.

Downloading a file¶

Existing files can be downloaded using the following two endpoints:

• GET /v2/company/file (files from company space)
• GET /v2/project/{project_id}/file (files from project space)

These endpoints generate download links which are valid for a certain period of time. Both endpoints accept the following parameters:

Example request

We request a download link for the previously uploaded example file EDE/EDE-bacnet.pdf which expires 10 minutes after our request.

GET /v2/company/file?path=EDE%2FEDE-bacnet.pdf&expiry=10m
host: https://api.aedifion.io
accept: application/json

Example response

The JSON response contains a download link with a limited validity.

HTTP/1.1 200
content-type: application/json

{
  "download_link": "https://s3.aedifion.io/demo-aedifion/EDE/EDE-bacnet.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=2BSg1Ot1SUiXfCh8RngsEGqVq%2F20200925%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20200925T130021Z&X-Amz-Expires=60&X-Amz-SignedHeaders=host&X-Amz-Signature=ae281892022b102d6fededec91545b72cbf5af8147d3f67c711fb48c8fa21149",
  "path": "EDE/EDE-bacnet.pdf",
  "valid_until": "2020-09-25T13:01:21.437236+00:00"
}

Copy-pasting the download link into a new browser-tab before its valid_until data triggers the actual download.

If we try to use the download link after its expiry, we are rightfully rejected with the following error.

HTTP/1.1 403
content-type: application/xml

<Error>
    <Code>AccessDenied</Code>
    <Message>Request has expired</Message>
    <Key>EDE/EDE-bacnet.pdf</Key>
    <BucketName>aedifion</BucketName>
    <Resource>/aedifion/EDE/EDE-bacnet.pdf</Resource>
    <RequestId>16380BE7DB7D4F6B</RequestId>
    <HostId>08cc1000-6f58-47fe-ac24-0c654ce12c1c</HostId>
</Error>

Replacing a file¶

As we have seen in the part on uploading files, uploading the same file twice fails. However, replacing or overwriting an existing file is a valid use case. To this end, the following endpoints can be used:

• PUT /v2/company/file (files in company space)
• PUT /v2/project/{project_id}/file (files in project space)

Both endpoints accept the following parameters:

Example request

We overwrite the file EDE/EDE-bacnet.pdf.

PUT /v2/company/files?path=EDE%2F
host: https://api.aedifion.io
accept: application/json

file: (binary)

Example response

The JSON response tells us that the requested file has been successfully replaced.

HTTP/1.1 201
content-type: application/json

{
  "resource": {
    "path": "EDE/EDE-bacnet.pdf"
  },
  "success": true
}

Note that replacing files only works when the target file actually exists. If either the folder or the file in it does not exist, the API responds with an error. Let's try this by replacing file EDE-bacnet.pdf in folder does-not-exist/.

HTTP/1.1 404
content-type: application/json

{
  "error": "File 'does-not-exist/EDE-bacnet.pdf' not found.",  
  "success": false
}

We're almost done with this tutorial - let's do some cleanup and delete our example file.

Deleting a file¶

Existing files can be deleted using the following endpoints:

• DELETE /v2/company/file (file from company space)
• DELETE /v2/project/{project_id}/file (file from project space)

Both endpoints accept the following parameters:

Example request

We delete the sample file EDE/EDE-bacnet.pdf that we uploaded at the start of this tutorial.

DELETE /v2/company/file?path=EDE%2FEDE-bacnet.pdf
host: https://api.aedifion.io
accept: application/json

Example response

The JSON response informs us that the file was successfully deleted.

HTTP/1.1 200
content-type: application/json

{
  "resource": {
    "path": "EDE/EDE-bacnet.pdf"
  },
  "success": true
}

Indeed, if we try to delete the file again by sending the above request a second time, the request fails because the file does not exist anymore.

HTTP/1.1 404
content-type: application/json

{
  "error": "File 'EDE/EDE-bacnet.pdf' not found.",
  "success": false
} 

Conclusion¶

In this tutorial, we've uploaded, listed, downloaded, replaced and deleted files. You're now ready to store company- or project-related files in the document database of the aedifion.io platform.