openapi: 3.0.3 info: title: Google Drive Sitemap Adapter API description: | HTTP adapter for generating XML sitemaps listing accessible Google Drive documents. ## Overview This adapter provides a single endpoint (`/sitemap.xml`) that generates a valid XML sitemap conforming to the sitemap protocol (https://www.sitemaps.org/protocol.html). The sitemap lists all documents accessible to the configured Google Service Account, with URLs pointing back to this adapter using document IDs. ## Authentication The adapter uses OAuth 2.0 Service Account authentication to access Google Drive. External clients do not need to authenticate with this API. ## Rate Limiting Google Drive API rate limits are handled gracefully. If rate limited, the adapter returns HTTP 429 with a Retry-After header indicating seconds until retry. ## Sitemap Protocol Compliance - Maximum 50,000 URLs per sitemap (protocol limit) - Each URL includes document ID and last modified timestamp - Always returns fresh data (no caching) version: 1.0.0 contact: name: API Support license: name: ISC servers: - url: http://localhost:3000 description: Development server - url: https://adapter.example.com description: Production server tags: - name: Sitemap description: XML sitemap generation paths: /sitemap.xml: get: summary: Generate XML sitemap description: | Returns an XML sitemap listing all accessible Google Drive documents. Each URL in the sitemap points to this adapter with a document ID: `{baseUrl}/{documentId}` The sitemap is generated on-demand (no caching) and may take up to 5 seconds for drives containing up to 10,000 documents. ## Sitemap Format Conforms to https://www.sitemaps.org/protocol.html: - ``: Absolute URL with document ID - ``: Last modified timestamp (ISO 8601) ## Document Retrieval Note: The URLs in the sitemap point back to this adapter, but document retrieval endpoints are not implemented. This adapter only generates sitemaps for discovery. operationId: getSitemap tags: - Sitemap responses: '200': description: Successfully generated sitemap headers: Content-Type: description: Always application/xml schema: type: string example: application/xml Content-Length: description: Size of sitemap in bytes schema: type: integer example: 204800 content: application/xml: schema: type: string format: xml example: | https://adapter.example.com/1BxAA_example123 2026-03-06T10:30:00.000Z https://adapter.example.com/1CyBB_example456 2026-03-05T14:20:00.000Z '401': description: Unauthorized - OAuth authentication failed headers: Content-Length: description: Always 0 (no response body) schema: type: integer example: 0 '429': description: Too Many Requests - Rate limited by Google Drive API headers: Retry-After: description: Seconds to wait before retrying schema: type: integer example: 60 Content-Length: description: Always 0 (no response body) schema: type: integer example: 0 '500': description: Internal Server Error headers: Content-Length: description: Always 0 (no response body) schema: type: integer example: 0 '503': description: Service Unavailable - Google Drive API is down headers: Content-Length: description: Always 0 (no response body) schema: type: integer example: 0 /{documentId}: get: summary: Document retrieval endpoint (NOT IMPLEMENTED) description: | This endpoint is referenced in sitemap URLs but is not implemented. The adapter only generates sitemaps; it does not serve documents. Clients should treat sitemap URLs as metadata only. operationId: getDocument tags: - Documents (Not Implemented) parameters: - name: documentId in: path description: Google Drive document ID required: true schema: type: string pattern: '^[a-zA-Z0-9_-]+$' example: 1BxAA_example123 responses: '404': description: Not Found - Document retrieval not implemented headers: Content-Length: description: Always 0 (no response body) schema: type: integer example: 0 /{anyOtherPath}: get: summary: All other paths description: | Any path other than `/sitemap.xml` returns 404 Not Found. operationId: notFound tags: - Routing parameters: - name: anyOtherPath in: path description: Any path other than /sitemap.xml required: true schema: type: string responses: '404': description: Not Found headers: Content-Length: description: Always 0 (no response body) schema: type: integer example: 0 components: schemas: Sitemap: type: object description: XML sitemap structure (logical representation, actual response is XML) properties: xmlns: type: string description: XML namespace for sitemap protocol example: http://www.sitemaps.org/schemas/sitemap/0.9 urls: type: array description: Array of URL entries items: $ref: '#/components/schemas/SitemapUrl' maxItems: 50000 SitemapUrl: type: object description: Single URL entry in sitemap required: - loc - lastmod properties: loc: type: string format: uri description: Absolute URL to document (adapter URL + document ID) example: https://adapter.example.com/1BxAA_example123 lastmod: type: string format: date-time description: Last modified timestamp in ISO 8601 format example: 2026-03-06T10:30:00.000Z Error: type: object description: Error response (note - most errors return empty body per spec) properties: code: type: integer description: HTTP status code example: 500 message: type: string description: Error message (not included in actual responses) example: Internal Server Error responses: UnauthorizedError: description: Unauthorized - OAuth authentication failed headers: Content-Length: schema: type: integer example: 0 RateLimitError: description: Too Many Requests - Rate limited by Google Drive API headers: Retry-After: description: Seconds to wait before retrying schema: type: integer example: 60 Content-Length: schema: type: integer example: 0 InternalError: description: Internal Server Error headers: Content-Length: schema: type: integer example: 0 ServiceUnavailable: description: Service Unavailable - Google Drive API is down headers: Content-Length: schema: type: integer example: 0 NotFound: description: Not Found - Path not recognized headers: Content-Length: schema: type: integer example: 0 externalDocs: description: Sitemap Protocol Specification url: https://www.sitemaps.org/protocol.html