Skip to content

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:

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

Access credentials

If you do not have a login yet, please contact us regarding a demo login. The login used in the example will not work!

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:

Parameter Datatype Type Required Description Example
service enum query no The service for which to request quotas. files

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:

Parameter Datatype Type Required Description Example
folder string query no Path to a subfolder where the uploaded file is put. If folder does not exist, folder is created. EDE/
file formData file yes The new file encoded as form data. (binary)

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:

Parameter Datatype Type Required Description Example
page integer query no The desired results page. 1
per_page integer query no The desired number of items per results page. 20
search string query no Term to search for in file paths. bacnet

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:

Parameter Datatype Type Required Description Example
path string query yes The full path of the file to download. EDE/EDE-bacnet.pdf
expiry string query no Time period when download expires. 10m

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>

S3-compatible API

Note that the error response is not in JSON format. This is because the download link does not trigger a request against the aedifion.io API. Instead it issues a request to the configured backend storage cluster for the files service (https://s3.aedifion.io) which purposely has been built with an S3-compatible API. We choose S3 because it has become a quasi standard for object storage and has wide adoption and support.

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:

Parameter Datatype Type Required Description Example
folder string query yes The path to the folder in which the file to replace resides. EDE/
file formData file yes The updated file encoded as form data. (binary)

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:

Parameter Datatype Type Required Description Example
path string query yes The full path of the file to delete. EDE/EDE-bacnet.pdf
file formData file yes The updated file encoded as form data. (binary)

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.


Last update: 2020-09-29