Oracle Database Collections API

openapi: 3.2.0
info:
  title: Oracle Database Oracle SODA (Simple Oracle Document Access) REST Collections API
  description: NoSQL-style document access API for Oracle Database. SODA for REST provides HTTP operations for managing JSON document collections, enabling CRUD operations, querying by example (QBE), bulk operations, and index management through a RESTful interface built on Oracle REST Data Services.
  version: 1.0.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/{schema}/soda/{version}
  description: SODA REST API Server
  variables:
    host:
      default: localhost
      description: ORDS server hostname
    port:
      default: '8443'
      description: ORDS server port
    schema:
      default: myschema
      description: Oracle Database schema name
    version:
      default: latest
      description: SODA API version
security:
- oauth2: []
- basicAuth: []
tags:
- name: Collections
  description: Collection management operations (create, list, delete)
paths:
  /:
    get:
      operationId: listCollections
      summary: Oracle Database List all collections
      description: Returns a list of collection names for the current database schema. Supports pagination through limit and fromID parameters.
      tags:
      - Collections
      parameters:
      - name: limit
        in: query
        description: Maximum number of collections to return
        schema:
          type: integer
          minimum: 1
      - name: fromID
        in: query
        description: Start listing from this collection name (inclusive)
        schema:
          type: string
      responses:
        '200':
          description: Collections retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Schema not found
  /{collection}:
    put:
      operationId: createCollection
      summary: Oracle Database Create a collection
      description: Creates a new document collection. This operation is idempotent - if the collection already exists, it returns 200 instead of 201. An optional request body can specify collection metadata configuration.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      requestBody:
        description: Optional collection metadata specification
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionMetadata'
      responses:
        '200':
          description: Collection already exists
        '201':
          description: Collection created successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{collection}/:
    delete:
      operationId: deleteCollection
      summary: Oracle Database Delete a collection
      description: Deletes the entire collection and all documents it contains. This operation cannot be undone.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      responses:
        '200':
          description: Collection deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    CollectionList:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Collection name
              properties:
                type: object
                description: Collection metadata properties
        hasMore:
          type: boolean
          description: Whether more collections exist beyond this page
    CollectionMetadata:
      type: object
      description: Optional collection configuration metadata
      properties:
        keyColumn:
          type: object
          properties:
            name:
              type: string
            sqlType:
              type: string
            maxLength:
              type: integer
            assignmentMethod:
              type: string
              enum:
              - UUID
              - GUID
              - SEQUENCE
              - CLIENT
        contentColumn:
          type: object
          properties:
            name:
              type: string
            sqlType:
              type: string
            compress:
              type: string
            cache:
              type: boolean
            encrypt:
              type: string
            validation:
              type: string
        versionColumn:
          type: object
          properties:
            name:
              type: string
            method:
              type: string
              enum:
              - UUID
              - TIMESTAMP
              - SHA256
              - MD5
              - NONE
        lastModifiedColumn:
          type: object
          properties:
            name:
              type: string
        readOnly:
          type: boolean
  responses:
    NotFound:
      description: The specified collection or document 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 parameter value
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    collectionParam:
      name: collection
      in: path
      required: true
      description: The name of the SODA collection
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /ords/{schema}/oauth/token
          scopes: {}
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  description: SODA for REST Documentation
  url: https://docs.oracle.com/en/database/oracle/simple-oracle-document-access/rest/