Index
1. Application Programming Interface (API)
1.1. Introduction
This API is designed following the principles of the REST (Representational State Transfer) architecture. It allows you to perform CRUD (Create, Read, Update, Delete) operations on system resources using standard HTTP methods and data representations in formats such as JSON or XML.
As you may notice in the base URL, only "api" is included and not "restful-api". This decision was made to simplify the URL for easier remembrance and to generalize its use, facilitating integration with your applications.
1.2. REST Principles
The API adheres to the following REST principles:
- Use of standard HTTP methods (GET, POST, PUT, DELETE).
- Identification of resources through unique URLs.
- Data representations in formats such as JSON or XML.
1.3. Base URL
The API can be accessed under the following base URL: https://donnzap.com/api/v1
1.4. Authentication Guide
To authenticate with the AP, include the `Authorization` header with the value of your secret key in each HTTP request. The secret key is a valid access token that you can obtain through the dashboard interface in the API keys section.
1.5. Endpoints
1.5.1. POST /object-storage/buckets
Description
Create a bucket
Usage
POST /object-storage/objects
Content-Type: multipart/form-data
Parameters
| Parameter |
Type |
Description |
Required |
| name |
string |
The name of the bucket. |
Yes |
Response Parameters (JSON)
| Parameter |
Type |
Description |
| message |
string |
A brief description of the request's result, e.g., "Request processed". |
| status |
string |
Indicates the result of the request, e.g., "success" or "error". |
| status_code |
integer |
The HTTP status code, e.g., 200 for success. |
| data |
object |
An object containing additional data. May be empty if no data is returned. |
{
"message": "Request processed",
"status": "success",
"status_code": 200,
"data": {}
}
Permissions
This operation requires the user to have the following permissions:
- Authorization API key in the header
Additional Notes
Ensure that the API key is included in the request headers for authentication.
1.5.2. DELETE /object-storage/buckets
Description
Delete one or more buckets
Usage
DELETE /object-storage/buckets
Content-Type: application/json
Parameters
| Parameter |
Type |
Description |
Required |
| buckets |
array |
An array where the elements are strings and each string has the name of the bucket. |
Yes |
Response Parameters (JSON)
| Parameter |
Type |
Description |
| message |
string |
A brief description of the request's result, e.g., "Request processed". |
| status |
string |
Indicates the result of the request, e.g., "success" or "error". |
| status_code |
integer |
The HTTP status code, e.g., 200 for success. |
| data |
object |
An object containing additional data. May be empty if no data is returned. |
{
"message": "Request processed",
"status": "success",
"status_code": 200,
"data": {}
}
Permissions
This operation requires the user to have the following permissions:
- Authorization API key in the header
Additional Notes
Ensure that the API key is included in the request headers for authentication.
1.5.3. POST /object-storage/objects
Description
The Chunked Upload API enables efficient and resilient uploads of large files by breaking them into smaller chunks. This approach is ideal for overcoming upload size limitations and for handling scenarios where network connections are unstable or prone to failure.
Usage
POST /object-storage/objects
Content-Type: multipart/form-data
Parameters
| Parameter |
Type |
Description |
Required |
| chunk |
file |
The file chunk being uploaded. |
Yes |
| chunk_index |
int |
The index of the current file chunk (starting from 0). |
Yes |
| total_chunks |
int |
The total number of chunks for the file. |
Yes |
| file_name |
string |
The name of the file being uploaded. |
Yes |
| bucket |
string |
The target bucket where the file will be stored. |
Yes |
Response Parameters (JSON)
| Parameter |
Type |
Description |
| message |
string |
A message indicating the result of the request. |
| status |
string |
The status of the request processing. |
| status_code |
integer |
The HTTP status code indicating the result of the request. |
| data.complete |
boolean |
Indicates whether the file upload process is complete. |
| data.object.name |
string |
The name of the uploaded file. |
| data.object.url |
string |
The URL where the uploaded file is stored. |
{
"message": "Request processed",
"status": "success",
"status_code": 200,
"data": {}
}
Or also considering that the last chunk has been stored and the object has been correctly loaded into the server
{
"data": {
"complete": true,
"object": {
"name": "test.html",
"url": "https://donnzap.com/api/v1/object-storage/buckets/1/test.html"
}
},
"message": "Request processed",
"status": "success",
"status_code": 200
}
Permissions
This operation requires the user to have the following permissions:
- Authorization API key in the header
Additional Notes
Ensure that the API key is included in the request headers for authentication.
Example using HTML and JavaScript code sent from the server to the client (in the browser):
<!DOCTYPE html><html lang="es">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>File Upload</title>
</head>
<body>
<input type="file" id="fileInput" />
<button onclick="uploadFile()">Upload</button>
<script>
async function uploadFile() {
const fileInput = document.getElementById('fileInput');
const file = fileInput.files[0];
const fileName = file ? file.name : null;
const bucketName = "test";
if (!file) {
console.log('Please select a file first.');
return;
}
const CHUNK_SIZE = 10 * 1024 * 1024; // 10MB per chunk
const totalChunks = Math.ceil(file.size / CHUNK_SIZE);
const uploadUrl = 'https://donnzap.com/api/v1/object-storage/objects';
for (let chunkIndex = 0; chunkIndex < totalChunks; chunkIndex++) {
const start = chunkIndex * CHUNK_SIZE;
const end = Math.min(file.size, start + CHUNK_SIZE);
const chunk = file.slice(start, end);
const formData = new FormData();
formData.append('chunk', chunk);
formData.append('chunk_index', chunkIndex);
formData.append('total_chunks', totalChunks);
formData.append('file_name', fileName);
formData.append('bucket', bucketName);
try {
const response = await fetch(uploadUrl, {
method: 'POST',
body: formData,
headers: {
Authorization: '<api_key>'
}
});
if (!response.ok) throw new Error('Upload failed');
} catch (error) {
console.error('Error:', error);
return;
}
}
console.log('Upload complete!');
}
</script>
</body>
</html>
#test.py
import donnzap
donnzap.api_key = "sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
response = donnzap.storage.object_storage.upload_file(
file="/home/username/main/images/123.jpg", # required The file must be a 'BytesIO', 'bytes' object, or a file path on disk.
file_name="123.jpg", # required
bucket="2" #required
)
print(response)
Placing the SDK in the correct location
To import the SDK in Python, you need to place the extracted folder in a place where Python can find it.
Option 1: Place the folder in your project directory
If you prefer to keep it simple, place the donnzap folder inside your project directory. For example:
/path/to/your_project/donnzap/
That is, alongside your main script (python3 script.py) or alongside your main package (python3 -m app).
After placing the folder there, you can import it into your Python code with:
Option 2: Install the SDK globally in the site-packages of your Python version