google-drive-content-adapter/specs/002-document-export/contracts/documents-export-api.md

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

GET /documents/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms HTTP/1.1
Host: localhost:3000

---

Response

Success Responses

200 OK - Document Exported

Headers:

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