114 lines
3.1 KiB
Markdown
114 lines
3.1 KiB
Markdown
# API Contract: Document Export Endpoint
|
|
|
|
**Feature**: 002-document-export
|
|
**Version**: 1.0
|
|
**Date**: 2026-03-09
|
|
**Base URL**: `http://localhost:3000` (configurable via config/default.json)
|
|
|
|
## Overview
|
|
|
|
HTTP endpoint for exporting Google Drive documents in multiple formats. Fetches document metadata, selects optimal export format, and streams content with appropriate headers.
|
|
|
|
---
|
|
|
|
## Endpoint
|
|
|
|
### Export Document
|
|
|
|
```
|
|
GET /documents/:documentId
|
|
```
|
|
|
|
Exports a single Google Drive document in the best available format (Markdown > HTML > PDF). For native PDF files, streams content directly.
|
|
|
|
---
|
|
|
|
## Request
|
|
|
|
### Path Parameters
|
|
|
|
| Parameter | Type | Required | Description | Example |
|
|
|-----------|------|----------|-------------|---------|
|
|
| `documentId` | string | Yes | Google Drive file ID | `1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms` |
|
|
|
|
### Headers
|
|
|
|
| Header | Required | Description |
|
|
|--------|----------|-------------|
|
|
| `Authorization` | Yes (implicit) | Google OAuth2 access token (handled by proxy auth layer) |
|
|
|
|
### Example Request
|
|
|
|
```http
|
|
GET /documents/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms HTTP/1.1
|
|
Host: localhost:3000
|
|
```
|
|
|
|
---
|
|
|
|
## Response
|
|
|
|
### Success Responses
|
|
|
|
#### 200 OK - Document Exported
|
|
|
|
**Headers**:
|
|
```http
|
|
Content-Type: text/x-markdown | text/html | application/pdf
|
|
Content-Disposition: inline; filename="[document-name].[extension]"
|
|
```
|
|
|
|
**Body**: Binary stream of document content
|
|
|
|
**Format Selection**:
|
|
- Markdown (text/x-markdown, .md): Preferred if available
|
|
- HTML (text/html, .html): Fallback if Markdown unavailable
|
|
- PDF (application/pdf, .pdf): Final fallback or native PDF files
|
|
|
|
---
|
|
|
|
### Error Responses
|
|
|
|
| Status Code | Message | Condition |
|
|
|-------------|---------|-----------|
|
|
| 401 | Unauthorized | User lacks permissions or auth failed |
|
|
| 403 | mimetype not supported | Document type not supported |
|
|
| 404 | Document not found | Invalid/non-existent document ID |
|
|
| 413 | Payload Too Large | Document exceeds 10MB |
|
|
| 500 | Export failed - unable to retrieve document content | Export link malformed/inaccessible |
|
|
| 502 | Bad Gateway - Google Drive API unavailable | Google Drive API error |
|
|
| 504 | Gateway Timeout | Operation exceeded 30 seconds |
|
|
|
|
---
|
|
|
|
## Behavior Specifications
|
|
|
|
### Format Selection Algorithm
|
|
|
|
1. Fetch document metadata from Google Drive API
|
|
2. Check if `exportLinks` exists:
|
|
- If yes: Select first available from [Markdown, HTML, PDF]
|
|
- If no and mimeType=PDF: Stream native PDF
|
|
- Otherwise: Return 403
|
|
|
|
### Timeouts & Limits
|
|
|
|
- **Timeout**: 30 seconds per request
|
|
- **Size Limit**: 10MB (10,485,760 bytes)
|
|
- **Streaming**: Content never buffered, piped directly
|
|
|
|
---
|
|
|
|
## Testing Contract
|
|
|
|
### Required Tests
|
|
|
|
1. **200**: Valid document returns content with correct headers
|
|
2. **401**: Invalid token returns Unauthorized
|
|
3. **403**: Unsupported mimetype returns error
|
|
4. **404**: Invalid ID returns Document not found
|
|
5. **413**: Document >10MB returns Payload Too Large
|
|
6. **504**: Timeout >30s returns Gateway Timeout
|
|
7. **Headers**: Content-Type and Content-Disposition correct
|
|
8. **Streaming**: Large files stream without buffering
|