Welcome to the CloudStore API documentation. CloudStore is a robust cloud storage solution that allows developers to integrate file storage, sharing, and management capabilities into their applications. This API provides a wide range of features to handle various aspects of cloud storage.
Our API is designed with RESTful principles, making it intuitive and easy to use. It supports a variety of operations including file uploads, downloads, sharing, and advanced search capabilities. Whether you're building a small application or a large-scale enterprise solution, CloudStore API offers the flexibility and scalability to meet your needs.
Throughout this documentation, you'll find detailed explanations, code examples, and best practices to help you make the most of CloudStore's features. We recommend starting with the Authentication section to set up your API access, then exploring the various endpoints and operations available.
Base URL for all API requests: https://api.cloudstore.com/v1
CloudStore API uses OAuth 2.0 for authentication, ensuring secure access to your data. This industry-standard protocol allows you to grant limited access to your CloudStore resources without exposing your credentials.
To use the API, you'll need to obtain an access token. This token should be included with every API request to authenticate your application. Access tokens are temporary and can be easily revoked, providing an additional layer of security.
We support multiple OAuth 2.0 flows, including the Authorization Code flow for web applications and the Client Credentials flow for server-to-server integrations. Choose the flow that best fits your application's architecture and security requirements.
Remember to keep your client secrets and access tokens secure. Never expose them in client-side code or public repositories.
Obtaining an Access Token
POST https://api.cloudstore.com/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET
The response will include an access_token which you should include in the Authorization header of all subsequent requests:
Authorization: Bearer YOUR_ACCESS_TOKEN
File operations are at the core of CloudStore's functionality. Our API provides a comprehensive set of endpoints to manage files, allowing you to perform actions such as uploading, downloading, and deleting files with ease.
When working with files, it's important to consider factors like file size limits, supported file types, and potential timeout issues for large file transfers. CloudStore supports resumable uploads for large files, ensuring that your file transfers are reliable even in unstable network conditions.
All file operations are performed over HTTPS, ensuring that your data remains encrypted in transit. Additionally, files are encrypted at rest using industry-standard encryption algorithms, providing an extra layer of security for your sensitive data.
Below, you'll find examples of common file operations. Note that these operations require authentication, so make sure to include your access token in the request headers.
Uploading a File
To upload a file, send a POST request to the /files endpoint:
POST /files
Content-Type: multipart/form-data
file: [binary data]
path: /documents/report.pdf
Downloading a File
To download a file, send a GET request to the /files/{file_id} endpoint:
GET /files/1234567890
Deleting a File
To delete a file, send a DELETE request to the /files/{file_id} endpoint:
DELETE /files/1234567890
Effective folder management is crucial for organizing your files in CloudStore. Our API provides a set of endpoints that allow you to create, modify, and navigate folder structures, giving you full control over your data organization.
Folders in CloudStore can be nested to create hierarchies, allowing for complex organizational structures. Each folder has a unique identifier, which you'll use when performing operations like moving files or creating subfolders.
It's important to note that folder operations may have cascading effects. For example, deleting a folder will also delete all its contents, including subfolders and files. Always use these operations with caution and implement appropriate confirmation steps in your application.
Below are examples of common folder management operations. Remember to include your authentication token in all requests.
Creating a Folder
To create a new folder, send a POST request to the /folders endpoint:
POST /folders
Content-Type: application/json
{
"name": "New Folder",
"parent_id": "0987654321"
}
Listing Folder Contents
To list the contents of a folder, send a GET request to the /folders/{folder_id}/contents endpoint:
GET /folders/0987654321/contents
Sharing is a key feature of CloudStore, allowing users to collaborate and distribute their files and folders efficiently. Our API provides robust sharing capabilities, enabling you to control access to your resources with fine-grained permissions.
When sharing files or folders, you can specify the level of access for each recipient, ranging from view-only to full edit permissions. You can also set expiration dates for shared links, ensuring that access is revoked after a certain time period.
It's important to consider the security implications of sharing. Always ensure that sensitive data is only shared with trusted parties, and consider using features like password protection for public links when dealing with confidential information.
Below are examples of how to share files and folders using the CloudStore API. As always, remember to authenticate your requests with your access token.
Sharing with Users
POST /share
Content-Type: application/json
{
"item_id": "1234567890",
"type": "file",
"email": "user@example.com",
"permission": "edit"
}
Generating a Public Link
POST /share/public
Content-Type: application/json
{
"item_id": "0987654321",
"type": "folder",
"expiration": "2024-12-31T23:59:59Z"
}
Versioning is a powerful feature of CloudStore that automatically maintains a history of changes made to your files. This allows you to track modifications, revert to previous versions, and ensure that no data is accidentally lost.
Each time a file is modified, CloudStore creates a new version while retaining the previous ones. This version history allows you to see how a file has changed over time, who made the changes, and when they were made. You can retrieve or restore any previous version of a file as needed.
Versioning is particularly useful for collaborative work environments, where multiple users might be editing the same files. It provides a safety net against accidental changes or deletions, and allows you to review the evolution of a document over time.
Below are examples of how to interact with file versions using the CloudStore API. As with all API requests, make sure to include your authentication token.
Listing File Versions
GET /files/1234567890/versions
Restoring a Previous Version
POST /files/1234567890/restore
Content-Type: application/json
{
"version_id": "v2"
}
CloudStore's search functionality allows you to quickly find files and folders within your storage space. Our API provides powerful search capabilities that go beyond simple filename matching, enabling you to locate your data efficiently even in large and complex storage structures.
The search feature supports various criteria including file names, content (for text-based files), metadata, and even the content of certain file types like PDFs or Word documents. You can combine multiple search parameters to create complex queries that pinpoint exactly what you're looking for.
Search results are paginated to ensure quick response times even for large result sets. You can specify the number of results per page and navigate through the pages of results as needed.
It's important to note that search operations can be resource-intensive, especially for large storage accounts. Consider implementing caching mechanisms in your application to improve performance for frequent searches.
Basic Search
GET /search?query=project+report
Advanced Search
GET /search?query=report&file_type=pdf&modified_after=2023-01-01T00:00:00Z
Webhooks provide a powerful way to receive real-time notifications about events occurring in your CloudStore account. Instead of constantly polling the API for changes, you can set up webhooks to notify your application immediately when specific events occur.
CloudStore supports a wide range of events that can trigger webhooks, including file uploads, modifications, deletions, sharing changes, and more. When an event occurs, CloudStore will send an HTTP POST request to the URL you specify, containing details about the event.
Implementing webhooks can significantly improve the responsiveness and efficiency of your application. However, it's important to ensure that your webhook endpoint is secure and can handle the expected volume of notifications. We recommend implementing authentication for your webhook endpoint and setting up retry logic for failed webhook deliveries.
Below are examples of how to register a webhook and what a webhook payload might look like. Remember to include your API authentication token when setting up webhooks.
Registering a Webhook
POST /webhooks
Content-Type: application/json
{
"url": "https://your-app.com/webhook",
"events": ["file.uploaded", "file.shared", "folder.created"]
}
Webhook Payload Example
{
"event": "file.uploaded",
"file_id": "1234567890",
"name": "report.pdf",
"size": 1048576,
"uploaded_by": "user@example.com",
"timestamp": "2024-03-15T14:30:00Z"
}
To ensure fair usage and maintain service stability, CloudStore implements rate limiting on API requests. Rate limiting helps prevent any single client from overwhelming our servers with too many requests in a short period, ensuring a consistent experience for all users.
Our rate limits are based on the number of requests made within a specific time window, typically per minute. The exact limits depend on your account type, with higher tiers generally allowing for more requests. If you exceed the rate limit, your requests will be temporarily blocked until the next time window begins.
It's important to design your application with these rate limits in mind. Implement proper error handling to catch rate limit errors, and consider implementing exponential backoff and retry mechanisms for important operations. For high-volume operations, you may want to implement request queuing in your application to smooth out traffic spikes.
Rate Limit Table
| Account Type | Requests per Minute | Burst Limit |
|---|---|---|
| Free | 60 | 100 |
| Pro | 300 | 500 |
| Enterprise | 1000 | 2000 |
Rate Limit Headers
CloudStore includes rate limit information in the response headers:
X-RateLimit-Limit: The maximum number of requests you're permitted to make per minute.X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.X-RateLimit-Reset: The time at which the current rate limit window resets in UTC epoch seconds.
Handling Rate Limit Errors
If you exceed the rate limit, you'll receive a 429 (Too Many Requests) response. Here's an example of how to handle this:
function makeApiRequest() {
fetch('https://api.cloudstore.com/v1/endpoint')
.then(response => {
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After');
console.log(`Rate limit exceeded. Retry after ${retryAfter} seconds`);
// Implement retry logic here
} else {
// Handle successful response
}
})
.catch(error => console.error('Error:', error));
}
Proper error handling is crucial for building robust applications that integrate with the CloudStore API. Our API uses standard HTTP response codes to indicate the success or failure of requests. Here's an overview of common error scenarios and how to handle them:
- 200 OK: The request was successful.
- 201 Created: The request was successful and a resource was created.
- 400 Bad Request: The request was invalid or cannot be served.
- 401 Unauthorized: The request requires authentication.
- 403 Forbidden: The server understood the request but refuses to authorize it.
- 404 Not Found: The requested resource could not be found.
- 429 Too Many Requests: You have exceeded the rate limit.
- 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
Error Response Format
When an error occurs, the API will return a JSON object with details about the error:
{
"error": {
"code": "invalid_request",
"message": "The request was invalid. Please check your parameters.",
"details": {
"field": "email",
"issue": "Invalid email format"
}
}
}
Best Practices for Error Handling
- Always check the HTTP status code of the response.
- Parse the error message and details from the response body.
- Implement appropriate retry logic for transient errors (e.g., rate limiting, temporary server issues).
- Log errors for debugging and monitoring purposes.
- Provide clear and helpful error messages to your users.
Example Error Handling
async function handleApiRequest(url, options) {
try {
const response = await fetch(url, options);
if (!response.ok) {
const errorData = await response.json();
throw new Error(errorData.error.message || 'An error occurred');
}
return await response.json();
} catch (error) {
console.error('API Error:', error);
// Handle the error appropriately (e.g., show a user-friendly message)
throw error;
}
}
By implementing robust error handling, you can create a more reliable and user-friendly application that gracefully manages API interactions and provides clear feedback to your users.