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