- Add post_policy and join_policy to lists, patchable per field - Add held message listing, approve and discard endpoints - Expose disabled and bounce_count on members - Reject '+' in list names, it is the command separator - Wire the router release into the daemon - Update OpenAPI description and README
193 lines
5.7 KiB
YAML
193 lines
5.7 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]}
|
|
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]}
|
|
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'}
|