291 lines
8.7 KiB
YAML
291 lines
8.7 KiB
YAML
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:
|
|
- `<loc>`: Absolute URL with document ID
|
|
- `<lastmod>`: 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: |
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
|
<url>
|
|
<loc>https://adapter.example.com/1BxAA_example123</loc>
|
|
<lastmod>2026-03-06T10:30:00.000Z</lastmod>
|
|
</url>
|
|
<url>
|
|
<loc>https://adapter.example.com/1CyBB_example456</loc>
|
|
<lastmod>2026-03-05T14:20:00.000Z</lastmod>
|
|
</url>
|
|
</urlset>
|
|
'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
|