Storage API Overview

The Informer Storage API provides endpoints for managing file storage. Files can be uploaded, retrieved, and searched. All routes are prefixed with /api.

Features

• File Upload - Upload files via multipart form data
• File Retrieval - Get file metadata and download contents
• File Search - Search files by filename

Authentication

All Storage API endpoints require authentication via session cookies or API tokens.

Endpoints

POST /api/files

Upload a new file.

Authentication: Required (session)

Request:

Multipart form data with file upload.

Form Fields:

Field	Type	Required	Description
file	file	Yes	File to upload (stream)

Example Request:

curl -X POST https://api.example.com/api/files \
  -H "Cookie: session=..." \
  -F "file=@document.pdf"

Response:

Returns the created file object with 201 Created status and Location header.

{
  "id": "file-123",
  "filename": "document.pdf",
  "contentType": "application/pdf",
  "size": 102400,
  "createdAt": "2024-01-15T10:30:00Z",
  "_links": {
    "self": { "href": "/api/files/file-123" },
    "inf:download": { "href": "/api/files/file-123/download" }
  }
}

---

GET /api/files/{id}

Get file metadata.

Authentication: Required (session)

Response:

{
  "id": "file-123",
  "filename": "document.pdf",
  "contentType": "application/pdf",
  "size": 102400,
  "embedded": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "_links": {
    "self": { "href": "/api/files/file-123" },
    "inf:download": { "href": "/api/files/file-123/download" }
  }
}

---

GET /api/files/{id}/download

Download file contents.

Authentication: Required (session)

Pre-blocks: file.lookup(params.id)

Response:

Returns file contents with appropriate Content-Type and Content-Disposition: attachment headers.

Example Response Headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"
Content-Length: 102400

---

GET /api/files

Search for files by filename.

Authentication: Required (session)

Query Parameters:

Parameter	Type	Description
filename	string	Filename to search for (partial match)

Example Request:

GET /api/files?filename=report

Response:

{
  "_links": {
    "self": { "href": "/api/files" }
  },
  "_embedded": {
    "inf:file": [
      {
        "id": "file-123",
        "filename": "monthly-report.pdf",
        "contentType": "application/pdf",
        "size": 102400,
        "createdAt": "2024-01-15T10:30:00Z",
        "_embedded": {
          "inf:owner": {
            "username": "john",
            "displayName": "John Doe",
            "_links": {
              "self": { "href": "/api/users/john" }
            }
          }
        },
        "_links": {
          "self": { "href": "/api/files/file-123" }
        }
      },
      {
        "id": "file-456",
        "filename": "quarterly-report.xlsx",
        "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "size": 51200,
        "createdAt": "2024-01-14T14:22:00Z"
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

File Properties

Property	Type	Description
id	string	Unique file identifier
filename	string	Original filename
contentType	string	MIME type
size	integer	File size in bytes
embedded	boolean	Whether file is embedded in another entity
role	string	File role (for template files: TEMPLATE, ASSET, DATA)
templateId	string	Associated template ID (if embedded)
datasetId	string	Associated dataset ID (if embedded)
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

Use Cases

Upload User Document

POST /api/files
Content-Type: multipart/form-data

file=@user-guide.pdf

Download File

GET /api/files/file-123/download

Search for Reports

GET /api/files?filename=report

Notes

• Files can be standalone or embedded in other entities (templates, datasets, etc.)
• Embedded files are managed through their parent entity's API
• File upload supports streaming for large files
• Downloaded files include original filename in Content-Disposition header