parsimony/docs/openapi.yaml

308 lines
10 KiB
YAML

openapi: 3.0.3
info:
title: Parsimony admin API
version: 1.0.0
servers:
- url: /api/v1
security:
- bearer: []
components:
securitySchemes:
bearer:
type: http
scheme: bearer
schemas:
List:
type: object
properties:
id: {type: integer}
name: {type: string}
domain: {type: string}
title: {type: string}
address: {type: string}
post_policy: {type: string, enum: [members, moderated]}
join_policy: {type: string, enum: [open, closed]}
archive_policy: {type: string, enum: [public, private, off], description: "public: browsable on the web; private: API only (default); off: not stored"}
Message:
type: object
properties:
id: {type: integer}
thread_id: {type: integer}
message_id: {type: string}
in_reply_to: {type: string}
subject: {type: string}
sender: {type: string, description: Display name of the author}
date: {type: string, format: date-time}
size: {type: integer}
body: {type: string, description: Only when reading a single message}
QueueItem:
type: object
properties:
id: {type: integer}
recipient: {type: string}
attempts: {type: integer, description: Failed attempts so far}
last_error: {type: string}
next_attempt: {type: string, format: date-time}
created_at: {type: string, format: date-time}
failed: {type: boolean, description: Given up for good (refused by the relay, or too old); never retried, listed for a week}
Member:
type: object
properties:
address: {type: string}
display_name: {type: string}
disabled: {type: boolean, description: Disabled after 3 hard bounces; re-adding the member re-enables it}
bounce_count: {type: integer}
Held:
type: object
properties:
id: {type: integer}
sender: {type: string}
subject: {type: string}
size: {type: integer}
created_at: {type: string, format: date-time}
Error:
type: object
properties:
error: {type: string}
responses:
Error:
description: Error
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
paths:
/health:
get:
security: []
summary: Liveness check
responses:
'200': {description: OK}
/lists:
get:
summary: List all lists
responses:
'200':
description: OK
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/List'}}
post:
summary: Create a list
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name, domain]
properties:
name: {type: string}
domain: {type: string}
title: {type: string}
responses:
'201':
description: Created
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'400': {$ref: '#/components/responses/Error'}
'409': {$ref: '#/components/responses/Error'}
/lists/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: Get a list
responses:
'200':
description: OK
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'404': {$ref: '#/components/responses/Error'}
patch:
summary: Update title and policies (send only the fields to change)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title: {type: string}
post_policy: {type: string, enum: [members, moderated]}
join_policy: {type: string, enum: [open, closed]}
archive_policy: {type: string, enum: [public, private, off]}
responses:
'200':
description: OK
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
delete:
summary: Delete a list and its members
responses:
'204': {description: Deleted}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/members:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: List members
responses:
'200':
description: OK
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/Member'}}
'404': {$ref: '#/components/responses/Error'}
post:
summary: Add a member (idempotent)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [address]
properties:
address: {type: string}
display_name: {type: string}
responses:
'201':
description: Created
content:
application/json:
schema: {$ref: '#/components/schemas/Member'}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/members/{address}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
- {name: address, in: path, required: true, schema: {type: string}}
delete:
summary: Remove a member
responses:
'204': {description: Removed}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/held:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: Messages waiting for moderation
responses:
'200':
description: OK
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/Held'}}
'404': {$ref: '#/components/responses/Error'}
/held/{id}/approve:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
post:
summary: Approve and deliver a held message
responses:
'204': {description: Delivered}
'404': {$ref: '#/components/responses/Error'}
'501': {$ref: '#/components/responses/Error'}
/held/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
delete:
summary: Discard a held message
responses:
'204': {description: Discarded}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/archive:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: List or search archived messages, newest first
parameters:
- {name: q, in: query, schema: {type: string}, description: Full-text search over subject, body and sender; words are ANDed}
- {name: limit, in: query, schema: {type: integer, default: 50, maximum: 200}}
- {name: offset, in: query, schema: {type: integer, default: 0}}
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
total: {type: integer}
messages: {type: array, items: {$ref: '#/components/schemas/Message'}}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
/archive/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: Read an archived message with its body
responses:
'200':
description: OK
content:
application/json:
schema: {$ref: '#/components/schemas/Message'}
'404': {$ref: '#/components/responses/Error'}
delete:
summary: Delete an archived message and its search entry
responses:
'204': {description: Deleted}
'404': {$ref: '#/components/responses/Error'}
/queue:
get:
summary: Outbound queue totals and up to 100 deliveries (failing ones first)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
pending: {type: integer}
retrying: {type: integer, description: Waiting deliveries that failed at least once}
failed: {type: integer, description: Deliveries given up for good, kept for a week}
oldest: {type: string, format: date-time, nullable: true}
items: {type: array, items: {$ref: '#/components/schemas/QueueItem'}}
/queue/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
delete:
summary: Discard a queued delivery
responses:
'204': {description: Discarded}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/archive/import:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
post:
summary: Import an mbox file into the archive
description: >
The request body is the mbox file itself (any content type, `application/mbox` by convention), streamed.
Idempotent: a message already archived (same Message-ID) is counted as a duplicate. Threads are rebuilt at the end.
Works whatever the list's archive policy. Messages that cannot be read are reported in the summary and do not
fail the request; a read error while receiving the body does (400), keeping the messages read so far.
requestBody:
required: true
content:
application/mbox:
schema: {type: string, format: binary}
responses:
'200':
description: Summary
content:
application/json:
schema:
type: object
properties:
imported: {type: integer}
duplicates: {type: integer}
failed: {type: integer}
errors: {type: array, items: {type: string}, description: The first 20 failures}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}