Skip to content

Document Service API

📄

A robust, multi-tenant document management REST API built with Java, Spring Boot, and PostgreSQL. Supports file upload, download, metadata management, and integration with multiple cloud storage providers: AWS, GCP, Azure, Cloudinary, and Local storage.

Features

Feature Description Icon
Multi-Tenant Support Isolates documents per tenant 🏢
File Upload/Download Upload and download documents (local & all supported providers) ⬆️⬇️
Metadata Management Store and query document metadata 🏷️
Pagination & Filtering Efficiently list and search documents 📄🔍
Cloud Storage Integrates with AWS, GCP, Azure, Cloudinary, and Local storage ☁️
RESTful API Clean, documented endpoints (OpenAPI/Swagger) 🔗
Auditing Tracks created/updated by and timestamps 🕒

Architecture Overview

flowchart TD
    A[Client] -->|REST API| B(DocumentController)
    B --> C[DocumentService]
    C --> D[DocumentRepository]
    C --> E[BucketProviderServices]
    D --> F[(PostgreSQL)]
    E --> G[(AWS/GCP/Azure/Cloudinary/Local)]
Hold "Alt" / "Option" to enable pan & zoom

API Endpoints

Method Endpoint Description Notes/Parameters
POST /api/v1/documents Upload a new document tenantId header, multipart form
GET /api/v1/documents/{documentId}/download Download a document by ID tenantId header
GET /api/v1/documents/{id} Get document information by ID
GET /api/v1/documents List all documents (paginated, filter) tenantId param, q param, pageable
GET /api/v1/documents/{userId}/user List documents uploaded by a user tenantId header, q param, pageable
DELETE /api/v1/documents/{id} Delete a document by ID
  • All endpoints are prefixed with /api/v1/documents.
  • Pagination and filtering supported via query params (q, page, size, etc.).
  • tenantId is required as a header or query parameter for most endpoints.
  • File upload uses multipart/form-data.

Example Request & Response Payloads

Upload Document

POST /api/v1/documents

Request (multipart/form-data): - file: (File, required) - createdBy: (String, optional) - updatedBy: (String, optional)

Response (200 OK): 

{
  "publicId": "string",
  "url": "string",
  "secureUrl": "string",
  "format": "pdf",
  "bytes": 12345,
  "width": 1000,
  "height": 1000,
  "resourceType": "raw",
  "createdAt": "2024-05-10T12:00:00Z",
  "originalFilename": "document.pdf",
  "signature": "string",
  "type": "upload",
  "etag": "string",
  "context": { "key": "value" },
  "imageMetadata": { "key": "value" },
  "exif": { "key": "value" },
  "pages": { "key": "value" },
  "version": "1",
  "provider": "AWS"
}

Download Document

GET /api/v1/documents/{documentId}/download - Response: File stream (Content-Disposition: attachment)

Get Document Info

GET /api/v1/documents/{id}

Response: 

{
  "id": "uuid",
  "userId": "uuid",
  "tenantId": "uuid",
  "fileName": "string",
  "fileType": "string",
  "fileSize": "string",
  "downloadUrl": "string",
  "created": "2024-05-10T12:00:00Z",
  "updated": "2024-05-10T12:00:00Z"
}

List Documents

GET /api/v1/documents - Response: Paginated list of DocumentResponse objects (see above)

List Documents by User

GET /api/v1/documents/{userId}/user - Response: Paginated list of DocumentResponse objects (see above)

Delete Document

DELETE /api/v1/documents/{id} - Response: 204 No Content

Sequence: Document Upload

sequenceDiagram
    participant U as User
    participant API as DocumentController
    participant S as DocumentService
    participant R as DocumentRepository
    participant B as BucketProviderService
    U->>API: POST /documents/upload (file, metadata)
    API->>S: validate & process
    S->>B: upload to selected provider (AWS/GCP/Azure/Cloudinary/Local)
    B-->>S: return file URL
    S->>R: save metadata
    R-->>S: confirm
    S-->>API: DocumentUploadResponse
    API-->>U: 201 Created + metadata
Hold "Alt" / "Option" to enable pan & zoom

Database Schema

erDiagram
    documents {
        UUID id PK
        TIMESTAMP created
        TIMESTAMP updated
        VARCHAR created_by
        VARCHAR updated_by
        VARCHAR file_name
        UUID user_id
        UUID tenant_id
        VARCHAR file_type
        VARCHAR file_size
        VARCHAR provider_id
        VARCHAR download_url
        VARCHAR bucket_provider
    }
Hold "Alt" / "Option" to enable pan & zoom

Supported Bucket Providers

The service supports the following storage providers: - AWS (Amazon Web Services S3) - GCP (Google Cloud Storage) - Azure (Microsoft Azure Blob Storage) - Cloudinary - Local (local file system)

You can configure which provider to use per document or tenant.

Getting Started

Prerequisites

  • Java 17+
  • PostgreSQL
  • Gradle

Setup

git clone https://github.com/olara-tech/document-service-java.git
cd document-service-java
./gradlew build

Database

  • Configure your PostgreSQL credentials in src/main/resources/application.yml.
  • Run Flyway migrations (auto on startup).

Run

./gradlew bootRun

Cloud & Bucket Provider Integration

  • Set your credentials for AWS, GCP, Azure, or Cloudinary in application.yml as needed.
  • Documents can be stored and served from any supported provider or the local file system.

Contributing

Pull requests are welcome! For major changes, please open an issue first.

License

MIT

Contact