You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

316 lines
8.6 KiB

openapi: 3.0.0
info:
title: Entities Service
version: 0.1.0
description:
Query and manipulate the Netz39 entities database.
contact:
email: tux@netz39.de
servers:
- url: http://localhost:8080/v0
tags:
- name: mgmt
description: Common management functions
paths:
/health:
get:
summary: Provides health information about the service
tags:
- mgmt
operationId: health
responses:
'200':
description: endpoint is healthy
content:
application/json:
schema:
$ref: '#/components/schemas/health'
'500':
$ref: '#/components/responses/InternalError'
/oas3:
get:
summary: get this endpoint's Open API 3 specification
tags:
- mgmt
responses:
'200':
description: returns the API spec
content:
text/plain:
schema:
type: string
'500':
$ref: '#/components/responses/InternalError'
/entities:
parameters:
- in: header
name: Authentication
schema:
type: string
description: Authentication token
post:
summary: Create an entity
tags:
- entities
requestBody:
content:
application/json:
schema:
type: object
description: Entity JSON
responses:
'201':
description: Entity has been created
content:
text/plain:
schema:
type: string
description: Entity ID (5 digit hex)
example: 1b3d5
'400':
$ref: '#/components/responses/InvalidInput'
'401':
$ref: '#/components/responses/AuthenticationRequired'
'403':
$ref: '#/components/responses/NotAllowed'
get:
summary: Retrieve all entities (can be limited to a specific time and active members)
tags:
- entities
parameters:
- in: query
name: time
schema:
type: string
format: date-time
description: Use database projection at given time
- in: query
name: fieldset
schema:
type: string
enum: [summary, sepa, all]
description: Select the set of fields returned for each entity
- in: query
name: activeMembersOnly
schema:
type: boolean
description: Return only active members (w/r/t the provided timestamp)
responses:
'200':
description: Request successfully processed
content:
application/json:
schema:
type: object
properties:
time:
type: string
format: date-time
fieldset:
type: string
enum: [summary, sepa, all]
activeMembersOnly:
type: boolean
entities:
type: array
items:
type: string
example: entities JSON
'400':
$ref: '#/components/responses/InvalidInput'
'401':
$ref: '#/components/responses/AuthenticationRequired'
'403':
$ref: '#/components/responses/NotAllowed'
/entities/{id}:
parameters:
- in: path
name: id
required: true
schema:
type: string
description: Entity ID
- in: header
name: Authentication
schema:
type: string
description: Authentication token
post:
summary: Update an existing entity
tags:
- entities
requestBody:
content:
application/json:
schema:
type: object
description: Entity JSON
responses:
'200':
description: Update was successful
'400':
$ref: '#/components/responses/InvalidInput'
'401':
$ref: '#/components/responses/AuthenticationRequired'
'403':
$ref: '#/components/responses/NotAllowed'
'404':
$ref: '#/components/responses/NotFound'
get:
summary: Retrieve a specific entity (can be limited to a specific time and active members)
tags:
- entities
parameters:
- in: query
name: time
schema:
type: string
format: date-time
description: Use database projection at given time
- in: query
name: fieldset
schema:
type: string
enum: [summary, sepa, all]
description: Select the set of fields returned for each entity
- in: query
name: activeMembersOnly
schema:
type: boolean
description: Return only active members (w/r/t the provided timestamp)
responses:
'200':
description: Entity has been found
content:
application/json:
schema:
type: object
description: Entity JSON
example: entities JSON
'400':
$ref: '#/components/responses/InvalidInput'
'401':
$ref: '#/components/responses/AuthenticationRequired'
'403':
$ref: '#/components/responses/NotAllowed'
'404':
$ref: '#/components/responses/NotFound'
/document/{id}/{type}:
parameters:
- in: path
name: id
required: true
schema:
type: string
description: Entity ID
- in: path
name: type
required: true
schema:
type: string
enum: [application, sepa]
description: Type of document to upload
- in: header
name: Authentication
schema:
type: string
description: Authentication token
post:
summary: Upload a PDF document for a member
description: Note that the entry must be updated with the URI obtained from this call
tags:
- document
requestBody:
description: The document
content:
'application/pdf':
schema:
type: string
format: binary
responses:
'201':
description: File has been stored ("created") locally, returns the URI for downloading the file
content:
text/plain:
schema:
type: string
format: uri
'303':
description: The file is already in storage, returns the URI for downloading the file
content:
text/plain:
schema:
type: string
format: uri
'401':
$ref: '#/components/responses/AuthenticationRequired'
'403':
$ref: '#/components/responses/NotAllowed'
'405':
$ref: '#/components/responses/InvalidInput'
'500':
$ref: '#/components/responses/InternalError'
get:
summary: Get a PDF document for a member
tags:
- document
responses:
'200':
description: Returns PDF data
content:
'application/pdf':
schema:
type: string
format: binary
'404':
$ref: '#/components/responses/NotFound'
'401':
$ref: '#/components/responses/AuthenticationRequired'
'403':
$ref: '#/components/responses/NotAllowed'
'405':
$ref: '#/components/responses/InvalidInput'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
health:
type: object
properties:
git-version:
type: string
api-version:
type: string
timestamp:
type: string
format: date-time
uptime:
type: string
example: ISO8601 conforming timespan
responses:
AuthenticationRequired:
description: Authentication is required (401)
NotAllowed:
description: The call is not allowed with the provided authentication (403)
InvalidInput:
description: One or more parameters are missing or invalid (400)
content:
text/plain:
schema:
type: string
example: error message
NotFound:
description: The specified object could not be found (404)
InternalError:
description: Internal error during execution (500)
content:
text/plain:
schema:
type: string
example: error message