Lania Storage – Dokumentasi Teknis API

Dokumentasi komunikasi dengan service lania-storage: base URL, endpoint, payload, response, dan error code.

---

Base URL & Umum

• Base URL: http(s)://<host>:<port>
  Default development: http://localhost:8090 (atur lewat env PORT).
• Prefix API: Semua endpoint file di bawah prefix /api.
• Health check: GET /health (tanpa prefix /api)
  Response: { "status": "ok", "timestamp": "<ISO>", "service": "lania-storage", "version": "1.0.0" }.
• Content-Type:
  • Upload: multipart/form-data.
  • Response JSON: application/json.

---

Endpoint

Method	Path	Deskripsi
POST	/api/files	Upload file
GET	/api/read/{path}	Baca file (inline, e.g. tampil di browser)
GET	/api/download/{path}	Download file (attachment)
GET	/api/pdf/{path}	Baca file PDF (untuk PDF viewer, inline + range)
DELETE	/api/files/{path}	Hapus file (soft delete)

{path} = path file di storage (bisa nested), contoh: data-tenant/tenant-uuid/1234567890.pdf.
Gunakan path yang dikembalikan saat upload (data.file_path) untuk read/download/pdf/delete.
(Path di URL harus di-encode jika ada karakter khusus.)

---

1. Upload file – POST /api/files

Request

• Content-Type: multipart/form-data
• Body (form-data):

Field	Type	Wajib	Deskripsi
file	file	Ya	Satu file (nama field bebas; disarankan file). Hanya file pertama yang diproses.
tenant_id	string (UUID)	Tidak	Tenant ID.
user_id	string (UUID)	Tidak	User ID.
is_public	boolean/string	Tidak	true / "true" = public. Default: false.
related_database	string	Tidak	Nama database (e.g. lania_common, lania_sso).
related_table	string	Tidak	Nama table yang dikaitkan.
related_id	string	Tidak	ID record terkait (UUID atau string).
related_service	string	Tidak	Service key (e.g. master-data, producement).
description	string	Tidak	Deskripsi file.

Validasi:

• Tipe file: png, jpg, jpeg, pdf, doc, docx, xls, xlsx, csv (validasi MIME + ekstensi).
• Ukuran: Maksimal 5 MB (default). Bisa diubah lewat env FILE_SIZE_LIMIT_MB.
  Jika melebihi limit, request bisa ditolak oleh Multer sebelum sampai controller.

Response sukses – 201 Created

{
  "message": "File uploaded successfully",
  "data": {
    "id": "uuid",
    "file_name": "original-name.pdf",
    "file_path": "data-tenant/<tenant-id>/<unique>.pdf",
    "file_type": "pdf",
    "file_size": 12345,
    "mime_type": "application/pdf",
    "description": null,
    "is_public": false,
    "related_database": null,
    "related_table": null,
    "related_id": null,
    "related_service": null,
    "created_at": "2025-02-20T00:00:00.000Z",
    "updated_at": "2025-02-20T00:00:00.000Z"
  }
}

Simpan data.file_path untuk dipakai di read / download / pdf / delete.

Response error (upload)

HTTP	Kondisi	Body JSON
400	Tidak ada file	{ "message": "File is required", "status": 400 }
400	Tipe file tidak diizinkan	{ "message": "File type not allowed. Allowed types: png, jpg, jpeg, pdf, doc, docx, xls, xlsx, csv", "status": 400 }
400	Ukuran file > limit	{ "message": "File size exceeds maximum limit of 5MB", "status": 400 }
500	Gagal upload (server/DB/storage)	{ "message": "Failed to upload file", "status": 500 }

Jika request melebihi limit ukuran di Multer, error bisa dikembalikan oleh global error handler (biasanya 413 atau 500, tergantung konfigurasi Multer).

---

2. Read file (inline) – GET /api/read/{path}

Menampilkan file di browser (inline).

Request

• Method: GET
• URL: /api/read/<file_path>
  Contoh: /api/read/data-tenant/abc-123/doc.pdf
file_path = nilai file_path dari response upload (bisa nested; encode URL jika ada karakter khusus).

Response sukses – 200 OK

• Body: Binary (isi file).
• Headers:
  • Content-Type: MIME file (e.g. application/pdf, image/png).
  • Content-Disposition: inline; filename="...".
  • Content-Length: ukuran byte.

Response error

HTTP	Kondisi	Body JSON
404	Record tidak ada / path tidak ditemukan	{ "message": "File not found", "status": 404 }
404	Ada di DB tapi tidak ada di object storage	{ "message": "File not found in object storage", "status": 404 }
404	Ada di DB tapi tidak ada di disk (local)	{ "message": "File not found on disk", "status": 404 }
500	Error server	{ "message": "Internal server error", "status": 500 }

---

3. Download file – GET /api/download/{path}

Mengunduh file sebagai attachment.

Request

• Method: GET
• URL: /api/download/<file_path>
  Sama seperti read, gunakan file_path dari response upload.

Response sukses – 200 OK

• Body: Binary (isi file).
• Headers:
  • Content-Type: application/octet-stream.
  • Content-Disposition: attachment; filename="...".
  • Content-Length: ukuran byte.

Response error

Sama seperti Read file (404 / 500, body JSON seperti di atas).

---

4. Read PDF (viewer) – GET /api/pdf/{path}

Khusus PDF: inline + header yang mendukung PDF viewer (cache, range request).

Request

• Method: GET
• URL: /api/pdf/<file_path>
  Path harus mengarah ke file yang tipe PDF (validasi di backend).

Response sukses – 200 OK

• Body: Binary (isi PDF).
• Headers:
  • Content-Type: application/pdf.
  • Content-Disposition: inline; filename="...".
  • Content-Length, Cache-Control, Accept-Ranges (untuk range request).

Response error

HTTP	Kondisi	Body JSON
400	Bukan file PDF	{ "message": "File is not a PDF", "status": 400 }
404	File tidak ditemukan (DB / object storage / disk)	{ "message": "File not found" } atau "File not found in object storage" / "File not found on disk", "status": 404
500	Error server	{ "message": "Internal server error", "status": 500 }

---

5. Delete file – DELETE /api/files/{path}

Soft delete: record di DB di-mark deleted; file di object storage / disk dihapus (hard delete dari storage).

Request

• Method: DELETE
• URL: /api/files/<file_path>
  Gunakan file_path dari response upload.

Response sukses – 200 OK

{
  "message": "File deleted successfully"
}

(Tidak ada field data.)

Response error

HTTP	Kondisi	Body JSON
404	File tidak ditemukan di DB	{ "message": "File not found", "status": 404 }
500	Error server	{ "message": "Failed to delete file", "status": 500 }

---

Ringkasan error code

Status	Arti	Dipakai di
200	OK	Delete sukses; Read/Download/PDF mengembalikan binary.
201	Created	Upload sukses.
400	Bad Request	Upload: no file, wrong type, file too large. PDF: not a PDF.
404	Not Found	Read / Download / PDF / Delete: file tidak ada (DB / storage / disk).
500	Internal Server Error	Kegagalan server (DB, storage, unexpected error).

Semua response error JSON memakai bentuk:

{
  "message": "<pesan human-readable>",
  "status": <http_status_code>
}

Di development, global error handler bisa menambah field stack pada response.

---

Contoh alur (service lain / frontend)

1. Upload:
   POST /api/files dengan multipart/form-data (file + optional metadata).
   Simpan response.data.file_path.
2. Tampil inline (gambar/PDF):
   GET /api/read/<file_path> atau untuk PDF: GET /api/pdf/<file_path>.
3. Download:
   GET /api/download/<file_path>.
4. Hapus:
   DELETE /api/files/<file_path>.

Path selalu nilai file_path dari response upload (bisa berisi slash, e.g. data-tenant/tenant-id/filename.pdf); encode untuk URL bila perlu.