components:
responses: {}
schemas:
AuthenticationError:
additionalProperties: false
properties:
message:
description: A human-readable description for the error for informational
purposes. The exact format of the message is unspecified, and implementations
should not rely on the presence of any specific information.
type: string
type:
description: A machine-processable identifier for the error. Typically corresponds
to the fully-qualified exception class (i.e. Python exception type).
type: string
uuid:
description: Unique identifier of the error. This identifier helps locate
the exact source of the error (e.g. find the log entry in the server log
stream). Make sure to include this identifier when contacting support.
format: uuid
type: string
required:
- type
- uuid
- message
title: Raised when the client fails to provide valid authentication credentials.
type: object
Credentials:
additionalProperties: false
properties:
client_id:
description: An API key.
type: string
client_secret:
description: The secret that corresponds to the API key.
type: string
required:
- client_id
- client_secret
title: Authentication credentials.
type: object
DataEvent:
additionalProperties: false
properties:
data:
contentEncoding: base64
type: string
required:
- data
type: object
Description:
additionalProperties: false
properties:
format:
description: The representation format for the text.
enum:
- text/html
- text/plain
- text/markdown
type: string
text:
description: The text string.
type: string
required:
- format
- text
title: A textual description as plain text or a well-known markup format.
type: object
ExampleType:
additionalProperties: false
properties:
count:
description: A sample property of an integer type.
type: integer
created_at:
description: A timestamp. The date type is identified with OpenAPI's format
string.
format: date-time
type: string
updated_at:
description: A timestamp.
format: date-time
type: string
uuid:
description: Uniquely identifies this instance.
format: uuid
type: string
value:
description: A sample property of a string type.
type: string
required:
- uuid
- count
- value
- created_at
- updated_at
title: An example type with a few properties.
type: object
Format:
enum:
- text/html
- text/plain
- text/markdown
title: Possible representation formats.
type: string
InternalServerError:
additionalProperties: false
properties:
message:
description: A human-readable description for the error for informational
purposes. The exact format of the message is unspecified, and implementations
should not rely on the presence of any specific information.
type: string
type:
description: A machine-processable identifier for the error. Typically corresponds
to the fully-qualified exception class (i.e. Python exception type).
type: string
uuid:
description: Unique identifier of the error. This identifier helps locate
the exact source of the error (e.g. find the log entry in the server log
stream). Make sure to include this identifier when contacting support.
format: uuid
type: string
required:
- type
- uuid
- message
title: The server encountered an unexpected error when processing the request.
type: object
Job:
additionalProperties: false
properties:
description:
$ref: '#/components/schemas/Description'
description: Additional information associated with the job.
id:
description: Job identifier.
format: uuid
type: string
started_at:
description: The timestamp (in UTC) when the job was started.
format: date-time
type: string
status:
description: Current job status.
enum:
- created
- running
- stopped
type: string
required:
- id
- status
- started_at
- description
title: A unit of execution.
type: object
NotFoundError:
additionalProperties: false
properties:
id:
description: The identifier of the entity not found, e.g. the UUID of a
job.
type: string
kind:
description: The entity that is not found such as a namespace, object, person
or job.
type: string
message:
description: A human-readable description for the error for informational
purposes. The exact format of the message is unspecified, and implementations
should not rely on the presence of any specific information.
type: string
type:
description: A machine-processable identifier for the error. Typically corresponds
to the fully-qualified exception class (i.e. Python exception type).
type: string
uuid:
description: Unique identifier of the error. This identifier helps locate
the exact source of the error (e.g. find the log entry in the server log
stream). Make sure to include this identifier when contacting support.
format: uuid
type: string
required:
- type
- uuid
- message
- id
- kind
title: Raised when an entity does not exist or has expired.
type: object
Person:
additionalProperties: false
properties:
family_name:
description: The person's family name (typically last name).
type: string
given_name:
description: The person's given name (typically first name).
type: string
required:
- family_name
- given_name
title: Represents a real person.
type: object
StatusEvent:
additionalProperties: false
description: This message is typically transmitted in a separate channel, e.g.
over a websocket connection.
properties:
id:
description: Uniquely identifies the job which the event corresponds to.
format: uuid
type: string
status:
description: The current status of the job.
enum:
- created
- running
- stopped
type: string
required:
- id
- status
title: Triggered when an out-of-band event takes place.
type: object
StatusResponse:
additionalProperties: false
description: This response serves as an acknowledgment, and may be followed
by several out-of-band events, transmitted e.g. over a websocket connection.
properties:
description:
description: Textual description associated with the response.
type: string
id:
description: Uniquely identifies the job which the response corresponds
to.
format: uuid
type: string
required:
- id
- description
title: Triggered synchronously as the immediate response to an asynchronous
operation.
type: object
Student:
additionalProperties: false
properties:
birth_date:
format: date
type: string
family_name:
description: The person's family name (typically last name).
type: string
given_name:
description: The person's given name (typically first name).
type: string
required:
- family_name
- given_name
title: A student at a university.
type: object
Teacher:
additionalProperties: false
properties:
family_name:
description: The person's family name (typically last name).
type: string
given_name:
description: The person's given name (typically first name).
type: string
subject:
type: string
required:
- family_name
- given_name
- subject
title: A lecturer at a university.
type: object
TokenProperties:
additionalProperties: false
properties:
access_token:
description: A base64-encoded access token string with header, payload and
signature parts.
type: string
expires_at:
description: Expiry of the access token. This field is informational, the
timestamp is also embedded in the access token.
format: date-time
type: string
required:
- access_token
- expires_at
title: Authentication/authorization token issued in response to an authentication
request.
type: object
URL:
format: uri
pattern: ^https?://
title: A Uniform Resource Locator (URL).
type: string
UUID:
format: uuid
type: string
UnreferencedType:
title: A type not referenced from anywhere else but passed as an additional
type to the initializer of the class `Specification`.
type: object
ValidationError:
additionalProperties: false
properties:
location:
additionalProperties: false
description: Location of where invalid input was found.
properties:
character:
description: Character number w.r.t. the beginning of the input (1-based).
type: integer
column:
description: Column number w.r.t. the beginning of the line (1-based).
type: integer
line:
description: Line number (1-based).
type: integer
required:
- line
- column
- character
type: object
message:
description: A human-readable description for the error for informational
purposes. The exact format of the message is unspecified, and implementations
should not rely on the presence of any specific information.
type: string
type:
description: A machine-processable identifier for the error. Typically corresponds
to the fully-qualified exception class (i.e. Python exception type).
type: string
uuid:
description: Unique identifier of the error. This identifier helps locate
the exact source of the error (e.g. find the log entry in the server log
stream). Make sure to include this identifier when contacting support.
format: uuid
type: string
required:
- type
- uuid
- message
- location
title: Raised when a JSON validation error occurs.
type: object
securitySchemes:
Default:
bearerFormat: JWT
description: Authenticates a request by verifying a JWT (JSON Web Token) passed
in the `Authorization` HTTP header.
scheme: bearer
type: http
info:
description: '# Introduction
This is introductory text for the API. You can write a Markdown document, save
it in a separate file and import the file as a global description by passing it
as a parameter to the initializer of the `Specification` class.
This specification has been generated with [python-openapi](https://github.com/hunyadi/pyopenapi).
'
title: Example specification
version: '1.0'
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
openapi: 3.1.0
paths:
/auth:
post:
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Credentials'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TokenProperties'
description: OK
'400':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/ValidationError'
required:
- error
type: object
description: The input is malformed.
'401':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/AuthenticationError'
required:
- error
type: object
description: Client lacks valid authentication credentials.
security: []
summary: Issues a JSON Web Token (JWT) to be passed to API calls.
tags:
- Endpoint
/job:
post:
parameters: []
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/URL'
type: array
description: A set of URLs to resources used to initiate the job.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UUID'
description: The unique identifier of the newly created job.
'400':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
oneOf:
- additionalProperties: false
description: This might be due to malformed request syntax or
invalid usage.
properties:
message:
description: A human-readable description for the error
for informational purposes. The exact format of the message
is unspecified, and implementations should not rely on
the presence of any specific information.
type: string
type:
description: A machine-processable identifier for the error.
Typically corresponds to the fully-qualified exception
class (i.e. Python exception type).
type: string
uuid:
description: Unique identifier of the error. This identifier
helps locate the exact source of the error (e.g. find
the log entry in the server log stream). Make sure to
include this identifier when contacting support.
format: uuid
type: string
required:
- type
- uuid
- message
title: The server cannot process the request due a client error.
type: object
- additionalProperties: false
properties:
location:
additionalProperties: false
description: Location of where invalid input was found.
properties:
character:
description: Character number w.r.t. the beginning of
the input (1-based).
type: integer
column:
description: Column number w.r.t. the beginning of the
line (1-based).
type: integer
line:
description: Line number (1-based).
type: integer
required:
- line
- column
- character
type: object
message:
description: A human-readable description for the error
for informational purposes. The exact format of the message
is unspecified, and implementations should not rely on
the presence of any specific information.
type: string
type:
description: A machine-processable identifier for the error.
Typically corresponds to the fully-qualified exception
class (i.e. Python exception type).
type: string
uuid:
description: Unique identifier of the error. This identifier
helps locate the exact source of the error (e.g. find
the log entry in the server log stream). Make sure to
include this identifier when contacting support.
format: uuid
type: string
required:
- type
- uuid
- message
- location
title: Raised when a JSON validation error occurs.
type: object
required:
- error
type: object
description: URL points to an invalid location. **OR** The input is malformed.
'500':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/InternalServerError'
required:
- error
type: object
description: Unexpected error while creating job.
summary: Creates a new job with the given data as input.
tags:
- JobManagement
/job/{job_id}:
delete:
parameters:
- description: Unique identifier for the job to terminate.
in: path
name: job_id
required: true
schema:
$ref: '#/components/schemas/UUID'
responses:
'200':
description: OK
summary: Terminates a job.
tags:
- JobManagement
get:
parameters:
- description: Unique identifier for the job to query.
in: path
name: job_id
required: true
schema:
$ref: '#/components/schemas/UUID'
- in: query
name: format
required: true
schema:
$ref: '#/components/schemas/Format'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
description: Status information about the job.
'400':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/ValidationError'
required:
- error
type: object
description: The input is malformed.
'404':
content:
application/json:
examples:
? ('NotFoundException', UUID('123e4567-e89b-12d3-a456-426614174000'),
'Job does not exist.', '12345678-1234-5678-1234-567812345678', 'job')
: value:
error:
id: 12345678-1234-5678-1234-567812345678
kind: job
message: Job does not exist.
type: NotFoundException
uuid: 123e4567-e89b-12d3-a456-426614174000
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/NotFoundError'
required:
- error
type: object
description: The job does not exist.
summary: Query status information about a job.
tags:
- JobManagement
patch:
description: May cause the job to be stopped and restarted.
parameters:
- description: Unique identifier for the job to update.
in: path
name: job_id
required: true
schema:
$ref: '#/components/schemas/UUID'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
description: Data to update the job with.
required: true
responses:
'200':
description: OK
'400':
content:
application/json:
schema:
additionalProperties: false
properties:
error:
$ref: '#/components/schemas/ValidationError'
required:
- error
type: object
description: The input is malformed.
summary: Updates information related to a job.
tags:
- JobManagement
/member/name/{family}/{given}:
get:
description: This operation has multiple response payload types.
parameters:
- in: path
name: family
required: true
schema:
type: string
- in: path
name: given
required: true
schema:
type: string
responses:
'201':
content:
application/json:
examples:
Lajos Szörnyeteg:
value:
family_name: Szörnyeteg
given_name: Lajos
Szerafin Ló:
value:
family_name: Ló
given_name: Szerafin
Szigfrid Bruckner:
value:
family_name: Bruckner
given_name: Szigfrid
Zoárd Nagy:
value:
family_name: Nagy
given_name: Zoárd
schema:
$ref: '#/components/schemas/Student'
description: A student at a university.
'202':
content:
application/json:
examples:
Makka Mikka:
value:
family_name: Mikka
given_name: Makka
subject: Négyszögletű Kerek Erdő
Mati Vacska:
value:
family_name: Vacska
given_name: Mati
subject: Négyszögletű Kerek Erdő
schema:
$ref: '#/components/schemas/Teacher'
description: A lecturer at a university.
summary: Find a member by their name.
tags:
- PeopleCatalog
/person/id/{id}:
get:
description: This operation has a custom route associated with it.
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Person'
description: OK
summary: Find a person by their identifier.
tags:
- PeopleCatalog
/person/name/{family}/{given}:
get:
description: This operation has a custom route associated with it.
parameters:
- in: path
name: family
required: true
schema:
type: string
- in: path
name: given
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
Levente Hunyadi:
value:
family_name: Hunyadi
given_name: Levente
schema:
$ref: '#/components/schemas/Person'
description: OK
summary: Find a person by their name.
tags:
- PeopleCatalog
/status/{job_id}:
get:
callbacks:
get_status_callback:
'{$request.query.callback}':
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StatusEvent'
responses:
'200':
description: OK
description: 'This operation is defined with the special return type of `Generator`.
`Generator[Y,S,R]` has the yield type
`Y`, the send type `S` of `None`, and the return type `R`. `R` is the response
type immediately returned by
a call to this operation. However, the client will receive out-of-band events
of type `Y` over a different
channel, e.g. a websocket connection or an HTTP callback.'
parameters:
- in: path
name: job_id
required: true
schema:
$ref: '#/components/schemas/UUID'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
description: OK
summary: Provides asynchronous status information about a job.
tags:
- JobManagement
security:
- Default: []
servers:
- url: http://example.com/api
tags:
- name: Endpoint
- name: PeopleCatalog
x-displayName: Operations related to people.
- description: Operations to create, inspect, update and terminate jobs.
name: JobManagement
x-displayName: Job management.
- description: 'A Uniform Resource Locator (URL).
<SchemaDefinition schemaRef="#/components/schemas/URL" />'
name: URL
- description: <SchemaDefinition schemaRef="#/components/schemas/UUID" />
name: UUID
- description: 'The server encountered an unexpected error when processing the request.
<SchemaDefinition schemaRef="#/components/schemas/InternalServerError" />'
name: InternalServerError
- description: 'Authentication credentials.
<SchemaDefinition schemaRef="#/components/schemas/Credentials" />'
name: Credentials
- description: 'Authentication/authorization token issued in response to an authentication
request.
<SchemaDefinition schemaRef="#/components/schemas/TokenProperties" />'
name: TokenProperties
- description: 'Raised when the client fails to provide valid authentication credentials.
<SchemaDefinition schemaRef="#/components/schemas/AuthenticationError" />'
name: AuthenticationError
- description: 'Raised when a JSON validation error occurs.
<SchemaDefinition schemaRef="#/components/schemas/ValidationError" />'
name: ValidationError
- description: 'Possible representation formats.
<SchemaDefinition schemaRef="#/components/schemas/Format" />'
name: Format
- description: 'A textual description as plain text or a well-known markup format.
<SchemaDefinition schemaRef="#/components/schemas/Description" />'
name: Description
- description: 'A unit of execution.
<SchemaDefinition schemaRef="#/components/schemas/Job" />'
name: Job
- description: 'Raised when an entity does not exist or has expired.
<SchemaDefinition schemaRef="#/components/schemas/NotFoundError" />'
name: NotFoundError
- description: 'A student at a university.
<SchemaDefinition schemaRef="#/components/schemas/Student" />'
name: Student
- description: 'A lecturer at a university.
<SchemaDefinition schemaRef="#/components/schemas/Teacher" />'
name: Teacher
- description: 'Represents a real person.
<SchemaDefinition schemaRef="#/components/schemas/Person" />'
name: Person
- description: 'Triggered synchronously as the immediate response to an asynchronous
operation.
This response serves as an acknowledgment, and may be followed by several out-of-band
events, transmitted e.g. over a websocket connection.
<SchemaDefinition schemaRef="#/components/schemas/StatusResponse" />'
name: StatusResponse
- description: 'Triggered when an out-of-band event takes place.
This message is typically transmitted in a separate channel, e.g. over a websocket
connection.
<SchemaDefinition schemaRef="#/components/schemas/StatusEvent" />'
name: StatusEvent
- description: <SchemaDefinition schemaRef="#/components/schemas/DataEvent" />
name: DataEvent
- description: 'An example type with a few properties.
<SchemaDefinition schemaRef="#/components/schemas/ExampleType" />'
name: ExampleType
- description: 'A type not referenced from anywhere else but passed as an additional
type to the initializer of the class `Specification`.
<SchemaDefinition schemaRef="#/components/schemas/UnreferencedType" />'
name: UnreferencedType
x-tagGroups:
- name: Operations
tags:
- Endpoint
- JobManagement
- PeopleCatalog
- name: Types
tags:
- AuthenticationError
- Credentials
- Description
- Format
- InternalServerError
- Job
- NotFoundError
- Person
- StatusEvent
- StatusResponse
- Student
- Teacher
- TokenProperties
- URL
- UUID
- ValidationError
- name: Events
tags:
- DataEvent
- name: Additional types
tags:
- ExampleType
- UnreferencedType