Oracle Database REST Services API

openapi: 3.2.0
info:
  title: Oracle Database Oracle REST Data Services (ORDS) REST Services API
  description: RESTful API for Oracle Database management, monitoring, and data access through Oracle REST Data Services. Provides 300+ endpoints across 17 categories including database administration, performance monitoring, Data Guard management, Data Pump operations, pluggable database lifecycle, APEX management, RDF graph operations, and transactional event queues.
  version: 25.4.0
  contact:
    name: Oracle Support
    url: https://support.oracle.com
    email: support@oracle.com
  license:
    name: Oracle Technology Network License
    url: https://www.oracle.com/downloads/licenses/standard-license.html
  termsOfService: https://www.oracle.com/legal/terms.html
servers:
- url: https://{host}:{port}/ords
  description: ORDS Server
  variables:
    host:
      default: localhost
      description: ORDS server hostname
    port:
      default: '8443'
      description: ORDS server port
security:
- oauth2: []
- basicAuth: []
tags:
- name: REST Services
  description: Custom REST API module, handler, and OAuth management
paths:
  /ords/rest/modules/:
    get:
      operationId: getRESTModules
      summary: Oracle Database Get all REST modules
      description: Returns a list of all custom REST API modules.
      tags:
      - REST Services
      responses:
        '200':
          description: REST modules retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RESTModuleList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRESTModule
      summary: Oracle Database Create a REST module
      description: Creates a new custom REST API module with SQL or PL/SQL handlers.
      tags:
      - REST Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRESTModuleRequest'
      responses:
        '201':
          description: REST module created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RESTModule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ords/rest/modules/{id}:
    put:
      operationId: updateRESTModule
      summary: Oracle Database Update a REST module
      description: Updates an existing REST API module.
      tags:
      - REST Services
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRESTModuleRequest'
      responses:
        '200':
          description: REST module updated successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /ords/rest/handlers/:
    get:
      operationId: getRESTHandlers
      summary: Oracle Database Get all REST handlers
      description: Returns a list of all REST API handlers.
      tags:
      - REST Services
      responses:
        '200':
          description: REST handlers retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RESTHandlerList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRESTHandler
      summary: Oracle Database Create a REST handler
      description: Creates a new REST API handler.
      tags:
      - REST Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRESTHandlerRequest'
      responses:
        '201':
          description: REST handler created successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ords/rest/handlers/{id}:
    delete:
      operationId: deleteRESTHandler
      summary: Oracle Database Delete a REST handler
      description: Deletes an existing REST API handler.
      tags:
      - REST Services
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: REST handler deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /ords/rest/clients/:
    get:
      operationId: getOAuthClients
      summary: Oracle Database Get all OAuth clients
      description: Returns a list of all registered OAuth clients.
      tags:
      - REST Services
      responses:
        '200':
          description: OAuth clients retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOAuthClient
      summary: Oracle Database Create an OAuth client
      description: Registers a new OAuth client for REST API authentication.
      tags:
      - REST Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOAuthClientRequest'
      responses:
        '201':
          description: OAuth client created successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ords/rest/clients/{id}:
    put:
      operationId: updateOAuthClient
      summary: Oracle Database Update an OAuth client
      description: Updates an existing OAuth client registration.
      tags:
      - REST Services
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOAuthClientRequest'
      responses:
        '200':
          description: OAuth client updated successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /ords/rest/privileges/:
    post:
      operationId: createPrivilege
      summary: Oracle Database Create a REST privilege
      description: Creates a new privilege for controlling access to REST resources.
      tags:
      - REST Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePrivilegeRequest'
      responses:
        '201':
          description: Privilege created successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ords/rest/roles/:
    post:
      operationId: createRole
      summary: Oracle Database Create a REST role
      description: Creates a new role for grouping REST privileges.
      tags:
      - REST Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleRequest'
      responses:
        '201':
          description: Role created successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ords/rest/autorest/:
    post:
      operationId: autoRESTEnableObject
      summary: Oracle Database REST enable a database object
      description: Enables automatic REST access for a database table, view, or PL/SQL object.
      tags:
      - REST Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoRESTRequest'
      responses:
        '201':
          description: Object REST enabled successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ords/properties/:
    get:
      operationId: getORDSProperties
      summary: Oracle Database Get ORDS properties
      description: Returns all ORDS configuration properties.
      tags:
      - REST Services
      responses:
        '200':
          description: Properties retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ORDSPropertyList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /ords/properties/{key}:
    put:
      operationId: setORDSProperty
      summary: Oracle Database Set an ORDS property
      description: Sets or updates an ORDS configuration property.
      tags:
      - REST Services
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ORDSPropertyValue'
      responses:
        '200':
          description: Property set successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: unsetORDSProperty
      summary: Oracle Database Unset an ORDS property
      description: Removes an ORDS configuration property, restoring the default value.
      tags:
      - REST Services
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Property unset successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    ORDSPropertyList:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
    CreateRESTModuleRequest:
      type: object
      required:
      - name
      - uri_prefix
      properties:
        name:
          type: string
        uri_prefix:
          type: string
        status:
          type: string
          enum:
          - PUBLISHED
          - NOT_PUBLISHED
        items_per_page:
          type: integer
    AutoRESTRequest:
      type: object
      required:
      - object_name
      - object_type
      properties:
        object_name:
          type: string
        object_type:
          type: string
          enum:
          - TABLE
          - VIEW
          - PACKAGE
          - PROCEDURE
          - FUNCTION
        object_alias:
          type: string
        schema:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        type:
          type: string
    RESTModuleList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RESTModule'
    CreateOAuthClientRequest:
      type: object
      required:
      - name
      - grant_type
      properties:
        name:
          type: string
        description:
          type: string
        grant_type:
          type: string
          enum:
          - authorization_code
          - client_credentials
        redirect_uri:
          type: string
          format: uri
    ORDSPropertyValue:
      type: object
      properties:
        value:
          type: string
    CreatePrivilegeRequest:
      type: object
      required:
      - name
      - label
      properties:
        name:
          type: string
        label:
          type: string
        description:
          type: string
        roles:
          type: array
          items:
            type: string
    RESTHandlerList:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              method:
                type: string
              source_type:
                type: string
              source:
                type: string
    OAuthClientList:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              client_id:
                type: string
              grant_type:
                type: string
    RESTModule:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        uri_prefix:
          type: string
        status:
          type: string
        items_per_page:
          type: integer
    CreateRoleRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
    CreateRESTHandlerRequest:
      type: object
      required:
      - method
      - source_type
      - source
      properties:
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - DELETE
        source_type:
          type: string
          enum:
          - collection/query
          - collection/feed
          - query
          - plsql
        source:
          type: string
  responses:
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required or credentials invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /ords/{schema}/oauth/token
          scopes: {}
        authorizationCode:
          authorizationUrl: /ords/{schema}/oauth/auth
          tokenUrl: /ords/{schema}/oauth/token
          scopes: {}
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  description: ORDS REST API Documentation
  url: https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/25.4/orrst/