- Add web.listen config (default 127.0.0.1:8081, empty disables) - Start the public web in app, close it with the rest - Add end-to-end test: archive stays private, becomes public, hides addresses, one-click unsubscribe works - Cover mutation survivors: attachments, first text part, multibyte cap, member id 0, page clamp, API limit cap, closing connections - Update OpenAPI, README and example config
245 lines
7.8 KiB
YAML
245 lines
7.8 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}
|
|
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'}
|