Skip to content

rest-endpoints.md

Latest commit

 

History

History
208 lines (154 loc) · 7.6 KB

rest-endpoints.md

File metadata and controls

208 lines (154 loc) · 7.6 KB
Raw

REST API Endpoints

Reference for WFM Archive REST API endpoints. This documentation reflects the actual implemented endpoints in the application.

Base URL

{base_url}/api

Authentication

All endpoints require authentication. Use the access_token as a query parameter:

?access_token={token}

Note: The application uses CUBA Platform's authentication mechanism. File upload operations require the cuba.restApi.fileUpload.enabled permission.

Implemented Document Management Endpoints

1. Add Document

POST /documents/{tenant}/{archive}

Archives a new document with metadata and file content.

Parameters

Name Type Location Required Description
tenant string path Yes Tenant identifier (e.g., "default")
archive string path Yes Archive identifier (e.g., "A10")
documenttype string form Yes Document type code
mapping string form No Mapping configuration name
metadata string form Yes Document metadata as JSON string
file file form Yes File to archive (multipart)

Request Example

curl -X POST "{base_url}/api/documents/default/A10" \
  -F "documenttype=INVOICE" \
  -F 'metadata={"invoiceNumber":"INV-2025-001","customerName":"Acme Corp","amount":1500.00}' \
  -F "file=@/path/to/invoice.pdf" \
  -F "access_token={token}"

Response

Returns a string response from the RestMappingService.adddocument() method.

Error Codes

  • 400 - File has no content
  • 403 - File upload not permitted for user
  • 500 - Internal server error

2. Retrieve Document

GET /documents/{tenant}/{archive}/{documentid}

Retrieves a specific document file. Returns the actual file content as a binary stream.

Parameters

Name Type Location Required Description
tenant string path Yes Tenant identifier (e.g., "default")
archive string path Yes Archive identifier (e.g., "A10")
documentid string path Yes MongoDB document ID (e.g., "62a83a7a65cb030b2903e75d")
access_token string query No Access token for authentication

Request Example

curl -X GET "{base_url}/api/documents/default/A10/62a83a7a65cb030b2903e75d?access_token={token}" \
  -o document.pdf

Response

  • Content-Type: Auto-detected MIME type using Apache Tika (e.g., application/pdf, image/png)
  • Body: Binary file content stream

Notes

  • The file is retrieved from MongoDB and served as temporary file
  • Content type is automatically detected using Apache Tika

3. Delete Document

DELETE /documents/{tenant}/{archive}/{documentid}

Deletes a specific document from the archive.

Parameters

Name Type Location Required Description
tenant string path Yes Tenant identifier
archive string path Yes Archive identifier
documentid string path Yes MongoDB document ID
access_token string query No Access token for authentication

Request Example

curl -X DELETE "{base_url}/api/documents/default/A10/62a83a7a65cb030b2903e75d?access_token={token}"

Response

Returns a string response from the RestMappingService.deletedocument() method.

Notes

  • Validates tenant and archive before deletion
  • Actual deletion is handled by RestMappingService

4. List Documents

GET /documents/{tenant}/{archive}

Retrieves a filtered list of documents from a specific archive. All metadata for each document is returned.

Parameters

Name Type Location Required Default Description
tenant string path Yes - Tenant identifier
archive string path Yes - Archive identifier
maps_name string query Yes - Folder name filter (e.g., "VENDOR")
maps_org string query Yes - Organization filter (use "null" if not needed)
maps_key string query Yes - Maps key filter (e.g., "4711")
andFilter array query No - AND filters - multiple values allowed (e.g., metadata.kundenr=4711)
orFilter array query No - OR filters - multiple values allowed
inFilter array query No - IN filters - multiple values allowed
fromSortDate string query No - Start date filter (format: yyyyMMdd, e.g., "20200201")
toSortDate string query No - End date filter (format: yyyyMMdd, e.g., "20220430")
offset integer query No 0 Number of records to skip
limit integer query No 25 Maximum records to return
sortorder string query No ASCENDING Sort order (ASCENDING or DESCENDING)

Request Example

curl -X GET "{base_url}/api/documents/default/A10" \
  -G \
  --data-urlencode "maps_name=VENDOR" \
  --data-urlencode "maps_org=null" \
  --data-urlencode "maps_key=4711" \
  --data-urlencode "andFilter=metadata.kundenr=4711" \
  --data-urlencode "andFilter=metadata.status=ACTIVE" \
  --data-urlencode "orFilter=metadata.documentType=Invoice" \
  --data-urlencode "fromSortDate=20200201" \
  --data-urlencode "toSortDate=20220430" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0" \
  --data-urlencode "sortorder=ASCENDING" \
  --data-urlencode "access_token={token}"

Response

Returns a string response from the RestMappingService.getdocuments() method containing the filtered documents and their metadata.

Filter Examples

  • andFilter: metadata.kundenr=4711 - Documents where kundenr equals 4711
  • orFilter: metadata.documentType=Invoice - Documents where type is Invoice
  • inFilter: Can be used for checking if a field value is in a list of values
  • Multiple filters of the same type can be specified to build complex queries

Features Not Implemented

The following endpoints are NOT implemented in the current version:

  • ❌ Advanced Search API (POST /documents/search)
  • ❌ Bulk Operations (bulk archive, bulk delete)
  • ❌ Export Endpoints (CSV, JSON, XML export)
  • ❌ Administrative Endpoints (document types, organizations via REST)
  • ❌ Webhook Management (register, list, delete webhooks)
  • ❌ Health/Metrics Endpoints (may exist in CUBA Platform but not in this controller)
  • ❌ Update/PATCH Operations (commented out in source code)

Error Handling

Errors are handled using the CustomRestAPIException class and return HTTP status codes:

  • 400 Bad Request: Invalid input (e.g., empty file)
  • 403 Forbidden: Permission denied (e.g., file upload not permitted)
  • 500 Internal Server Error: Server-side errors

Implementation Notes

  1. Authentication: Uses CUBA Platform's authentication mechanism with access_token parameter
  2. File Handling: Files are processed through CUBA's FileUploadingAPI and stored as temporary files
  3. Content Detection: Uses Apache Tika for automatic MIME type detection
  4. Service Delegation: Most business logic is delegated to:
    • RestMappingService for document operations
    • MongoService for file retrieval
    • RestCachedService for validation

Response Format

Note: Unlike typical REST APIs that return JSON, this implementation returns string responses from the underlying service methods. The exact format depends on the RestMappingService implementation.

Next Steps