395 lines
12 KiB
JSON
395 lines
12 KiB
JSON
{
|
|
"openapi": "3.0.0",
|
|
"info": {
|
|
"title": "REST4i - Database Services",
|
|
"description": "Enhanced database services with connection pooling and multiple output formats. Execute SQL queries with support for JSON, XML, CSV, HTML, and Excel output formats.",
|
|
"version": "1.0.7-rest4i",
|
|
"contact": {
|
|
"name": "API Support",
|
|
"url": "https://github.com/rest4i"
|
|
},
|
|
"license": {
|
|
"name": "Apache 2.0",
|
|
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
|
|
}
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "/rest4i/api"
|
|
}
|
|
],
|
|
"tags": [
|
|
{
|
|
"name": "Database Services",
|
|
"description": "Enhanced database services with connection pooling and multiple output formats."
|
|
}
|
|
],
|
|
"paths": {
|
|
"/v1/database/query": {
|
|
"post": {
|
|
"tags": ["Database Services"],
|
|
"summary": "Execute SQL query with multiple output formats",
|
|
"description": "Execute a SQL query against the IBM i database with support for multiple output formats including JSON, XML, CSV, HTML, and Excel.",
|
|
"operationId": "executeQuery",
|
|
"security": [
|
|
{
|
|
"bearerHttpAuthentication": []
|
|
},
|
|
{
|
|
"basicHttpAuthentication": []
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"description": "The SQL query and formatting options",
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DatabaseQueryRequest"
|
|
},
|
|
"example": {
|
|
"sql": "SELECT * FROM QSYS2.SYSTABLES FETCH FIRST 10 ROWS ONLY",
|
|
"format": "json",
|
|
"treatWarningsAsErrors": false,
|
|
"alwaysReturnSQLStateInformation": false
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "SQL query executed successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApiResponse"
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"rowCount": 2,
|
|
"data": [
|
|
{
|
|
"TABLE_SCHEMA": "QSYS2",
|
|
"TABLE_NAME": "SYSTABLES",
|
|
"TABLE_TYPE": "SYSTEM TABLE"
|
|
}
|
|
]
|
|
},
|
|
"message": "Query executed successfully",
|
|
"timestamp": "2024-01-15T10:30:00Z"
|
|
}
|
|
},
|
|
"application/xml": {
|
|
"example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><result><success>true</success><data><row><TABLE_SCHEMA>QSYS2</TABLE_SCHEMA></row></data></result>"
|
|
},
|
|
"text/csv": {
|
|
"example": "TABLE_SCHEMA,TABLE_NAME,TABLE_TYPE\n\"QSYS2\",\"SYSTABLES\",\"SYSTEM TABLE\""
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Bad request - invalid SQL or parameters",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApiResponse"
|
|
},
|
|
"example": {
|
|
"success": false,
|
|
"error": {
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "Validation failed",
|
|
"timestamp": "2024-01-15T10:30:00Z",
|
|
"validationErrors": [
|
|
{
|
|
"field": "sql",
|
|
"message": "SQL query is required"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"description": "Unauthorized request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "Forbidden - dangerous SQL detected",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"get": {
|
|
"tags": ["Database Services"],
|
|
"summary": "Execute SQL query via GET with multiple output formats",
|
|
"description": "Execute a SQL query via GET request with support for multiple output formats.",
|
|
"operationId": "executeQueryGet",
|
|
"security": [
|
|
{
|
|
"bearerHttpAuthentication": []
|
|
},
|
|
{
|
|
"basicHttpAuthentication": []
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "sql",
|
|
"in": "query",
|
|
"description": "The SQL query to execute",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"example": "SELECT * FROM QSYS2.SYSTABLES FETCH FIRST 10 ROWS ONLY"
|
|
},
|
|
{
|
|
"name": "format",
|
|
"in": "query",
|
|
"description": "Output format: json, xml, csv, html, excel",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": ["json", "xml", "csv", "html", "excel"],
|
|
"default": "json"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "SQL query executed successfully"
|
|
},
|
|
"400": {
|
|
"description": "Bad request - invalid SQL or parameters",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"description": "Unauthorized request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "Forbidden - dangerous SQL detected",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Problem"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"DatabaseQueryRequest": {
|
|
"type": "object",
|
|
"properties": {
|
|
"sql": {
|
|
"type": "string",
|
|
"description": "The SQL query to execute",
|
|
"example": "SELECT * FROM QSYS2.SYSTABLES FETCH FIRST 10 ROWS ONLY"
|
|
},
|
|
"format": {
|
|
"type": "string",
|
|
"enum": ["json", "xml", "csv", "html", "excel"],
|
|
"default": "json",
|
|
"description": "Output format for the query results"
|
|
},
|
|
"treatWarningsAsErrors": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Whether to treat SQL warnings as errors"
|
|
},
|
|
"alwaysReturnSQLStateInformation": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Whether to always return SQL state information"
|
|
}
|
|
},
|
|
"required": ["sql"]
|
|
},
|
|
"ApiResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates if the operation was successful"
|
|
},
|
|
"data": {
|
|
"description": "The response data (varies by endpoint)"
|
|
},
|
|
"error": {
|
|
"$ref": "#/components/schemas/ErrorInfo"
|
|
},
|
|
"pagination": {
|
|
"$ref": "#/components/schemas/PaginationInfo"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Success or informational message"
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO-8601 formatted timestamp of the response"
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional metadata about the response"
|
|
}
|
|
},
|
|
"required": ["success", "timestamp"]
|
|
},
|
|
"ErrorInfo": {
|
|
"type": "object",
|
|
"properties": {
|
|
"code": {
|
|
"type": "string",
|
|
"description": "Error code identifying the type of error"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable error message"
|
|
},
|
|
"details": {
|
|
"type": "string",
|
|
"description": "Additional error details"
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO-8601 formatted timestamp when error occurred"
|
|
},
|
|
"validationErrors": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ValidationError"
|
|
},
|
|
"description": "List of validation errors if applicable"
|
|
}
|
|
},
|
|
"required": ["code", "message"]
|
|
},
|
|
"ValidationError": {
|
|
"type": "object",
|
|
"properties": {
|
|
"field": {
|
|
"type": "string",
|
|
"description": "The field that failed validation"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "The validation error message"
|
|
},
|
|
"rejectedValue": {
|
|
"description": "The value that was rejected during validation"
|
|
}
|
|
},
|
|
"required": ["field", "message"]
|
|
},
|
|
"PaginationInfo": {
|
|
"type": "object",
|
|
"properties": {
|
|
"page": {
|
|
"type": "integer",
|
|
"description": "Current page number (0-based)"
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "Number of elements per page"
|
|
},
|
|
"totalPages": {
|
|
"type": "integer",
|
|
"description": "Total number of pages"
|
|
},
|
|
"totalElements": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Total number of elements across all pages"
|
|
}
|
|
}
|
|
},
|
|
"Problem": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string"
|
|
},
|
|
"message": {
|
|
"type": "string"
|
|
},
|
|
"code": {
|
|
"type": "integer",
|
|
"format": "int32"
|
|
},
|
|
"details": {
|
|
"type": "object"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"securitySchemes": {
|
|
"bearerHttpAuthentication": {
|
|
"type": "http",
|
|
"description": "Bearer token authentication.",
|
|
"scheme": "bearer",
|
|
"bearerFormat": "Bearer [token]"
|
|
},
|
|
"basicHttpAuthentication": {
|
|
"type": "http",
|
|
"description": "Basic authentication.",
|
|
"scheme": "basic"
|
|
}
|
|
}
|
|
}
|
|
}
|