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
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
|
|
|