Initial Version of sitemap.xml spec
This commit is contained in:
290
specs/001-drive-proxy-adapter/contracts/openapi.yaml
Normal file
290
specs/001-drive-proxy-adapter/contracts/openapi.yaml
Normal file
@@ -0,0 +1,290 @@
|
||||
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
|
||||
Reference in New Issue
Block a user