{
"openapi": "3.0.3",
"info": {
"title": "Central Configuration Server API",
"version": "2024.07.01",
"description": "<p>Last Update: July 2024</p>\n\nThe Central Configuration Server API provides comprehensive endpoints that allows ORDS (Oracle Rest Data Services) to retrieve global and pool-specific configurations from the central configuration server. Use this API to setup and configure your own central configuration server for ORDS.<p> With centralized configurations ORDS nodes will be configured to point to a centralized configuration URL that provides access to the configuration state, rather than reading the configuration state from a disk based folder. </p> <p>The configuration server will be specified via a Java System property named config.url . Access to the centralized configuration URL will need to be secured. Another system property config.wallet will be used to provide the credentials to be used when connecting to the centralized configuration URL.</p>",
"license": {
"name": "ORDS License",
"url": "https://www.oracle.com/rest"
}
},
"externalDocs": {
"description": "Find out more about ORDS",
"url": "https://www.oracle.com/rest"
},
"servers": [
{
"url": "https://central-config.example.com",
"description": "Central Configuration Server"
}
],
"tags": [
{
"name": "General",
"description": "General Endpoints"
}
],
"paths": {
"/central/v1/config": {
"get": {
"tags": [
"General"
],
"summary": "Retrieve global configuration",
"description": "<p>Retrieves the global configuration stored in the central configuration server. The global configuration contains settings that apply across the entire ORDS instance.</p><p> Configuration use the standard JSON properties format, where each configuration setting contains a key and a corresponding value.</p>",
"operationId": "getGlobalConfig",
"parameters": [
{
"$ref": "#/components/parameters/AcceptHeader"
},
{
"$ref": "#/components/parameters/AuthorizationHeader"
},
{
"$ref": "#/components/parameters/RequestIdHeader"
}
],
"responses": {
"200": {
"description": "Global configuration returned successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GlobalConfigResponse"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication.Bearer access token was not provided in Authorization header, token could not be decoded, or token was invalid.",
"content": {
"application/json": {
"example": {
"message": "string",
"code": "string"
}
}
}
},
"404": {
"description": "Not Found - Global configuration not found",
"content": {
"application/json": {
"example": {
"message": "string",
"code": "string"
}
}
}
}
}
}
},
"/central/v1/config/pool/{host}": {
"get": {
"tags": [
"General"
],
"summary": "Retrieve pool-specific configuration",
"description": "<p> Retrieves the configuration for a specific pool from the central server.The pool configuration file contains informations about a pool. Configuration files use the standard JSON properties format, where each configuration setting contains a key and a corresponding value.</p> <p>Note that the response should include an ETag which changes if the configuration changes.</p>",
"operationId": "getPoolConfig",
"parameters": [
{
"$ref": "#/components/parameters/AcceptHeader"
},
{
"$ref": "#/components/parameters/AuthorizationHeader"
},
{
"$ref": "#/components/parameters/RequestIdHeader"
},
{
"$ref": "#/components/parameters/IfNoneMatchHeader"
},
{
"name": "host",
"in": "path",
"required": true,
"description": "Identifier for the pool whose configuration is to be retrieved.",
"schema": {
"type": "string",
"example": "mydatabase"
}
}
],
"responses": {
"200": {
"description": "Pool configuration returned successfully",
"headers": {
"ETag": {
"description": "ETag for the returned configuration",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PoolConfigResponse"
}
}
}
},
"304": {
"description": "Not Modified - The configuration has not changed since the last request",
"content": {
"application/json": {
"example": {
"message": "string",
"code": "string"
}
}
}
},
"401": {
"description": "Unauthorized - Invalid or missing authentication.Bearer access token was not provided in Authorization header, token could not be decoded, or token was invalid.",
"content": {
"application/json": {
"example": {
"message": "string",
"code": "string"
}
}
}
},
"404": {
"description": "Not Found - No matching mapping is found for the requested pool",
"content": {
"application/json": {
"example": {
"message": "string",
"code": "string"
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"AcceptHeader": {
"name": "Accept",
"in": "header",
"required": false,
"description": "Indicates the media type(s) that ORDS is able to understand. The central configuration server uses this header to select an appropriate response format.",
"schema": {
"type": "string",
"example": "application/json"
}
},
"AuthorizationHeader": {
"name": "Authorization",
"in": "header",
"required": true,
"description": "Contains the credentials to authenticate ORDS with the server. Typically used to pass a Bearer token.",
"schema": {
"type": "string",
"example": "Bearer abcdef123456"
}
},
"RequestIdHeader": {
"name": "Request-Id",
"in": "header",
"required": true,
"description": "A unique identifier for the request, which can be used for tracking and debugging purposes. This ID helps correlate ORDS requests with server logs.",
"schema": {
"type": "string",
"example": "123e4567-e89b-12d3-a456-426614174000"
}
},
"IfNoneMatchHeader": {
"name": "If-None-Match",
"in": "header",
"required": true,
"description": "Used to make conditional requests based on the ETag (entity tag) of a resource. If the ETag matches the current version of the resource, the server responds with a 304 Not Modified status instead of returning the resource.",
"schema": {
"type": "string",
"example": "34f7a3113803f8ed3b8fd7ce5656ebec"
}
}
},
"schemas": {
"GlobalConfigResponse": {
"type": "object",
"properties": {
"settings": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Key-value pairs of configuration settings. Under \"Settings\", you can define your custom settings. Please refer to the following documentation for a better understanding of what configuration settings are available for the global configuration file [Oracle REST Data Services Configuration Files](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/24.2/ordig/about-REST-configuration-files.html).",
"example": {
"restEnabledSql.active": true,
"feature.sdw": true,
"security.externalHostMappingHeader": "poolname"
}
},
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rel": {
"type": "string",
"description": "Indicates the relationship of the link to the current context."
},
"href": {
"type": "string",
"description": "Specifies the URL associated with the link."
},
"templated": {
"type": "boolean",
"description": "Specifies whether the URL is templated (contains placeholders) or not."
}
},
"required": [
"rel",
"href"
],
"example": [
{
"rel": "collection",
"href": "http://central-config.example.com:8585/central/v1/config/"
},
{
"rel": "self",
"href": "http://central-config.example.com:8585/central/v1/config/"
},
{
"rel": "search",
"href": "http://central-config.example.com:8585/central/v1/config/pool/{host}",
"templated": true
}
]
},
"description": "Under \"links\" (Array), each entry represents a hyperlink related to the configuration, with specific relationships (e.g., \"collection\", \"self\", \"search\") and associated URLs. The \"search\" link is marked as templated, indicating that it contains a placeholder {host} which can be replaced with an actual value when making a request.\nThis array contains links relevant to the configuration\n- **rel** (String) Indicates the relationship of the link to the current context.\n- **href** (String) Specifies the URL associated with the link.\n- **templated** (Boolean) Specifies whether the URL is templated (contains placeholders) or not.\n"
}
}
},
"PoolConfigResponse": {
"type": "object",
"properties": {
"database": {
"type": "object",
"properties": {
"pool": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"settings": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"example": {
"db.wallet.zip": "UEsDBBQACAgIAOMid1IAAAAAAAAAAAAAAAALAAAAY3dhbGxldC5zc28BdRuH4TjA...",
"feature.sdw": true,
"plsql.gateway.mode": "proxied",
"restEnabledSql.active": true
},
"description": "Please refer to the following documentation for better understanding of what configuration settings are available for the pool configuration file [Understanding the Configurable Settings](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/24.2/ordig/about-REST-configuration-files.html)\n"
}
}
}
}
}
}
}
}
}
}