Oracle Database Documents API

openapi: 3.1.0
info:
  title: Oracle Database Oracle Cloud Infrastructure Database APEX Documents API
  description: API for managing Oracle Database services in Oracle Cloud Infrastructure (OCI). Provides management of DB Systems, Autonomous Databases, Exadata infrastructure, database backups, Data Guard associations, database homes, and related cloud database resources.
  version: '20160918'
  contact:
    name: Oracle Cloud Support
    url: https://support.oracle.com
    email: cloud-support@oracle.com
  license:
    name: Oracle Cloud Infrastructure Terms
    url: https://www.oracle.com/cloud/free/oci-terms.html
  termsOfService: https://www.oracle.com/legal/terms.html
servers:
- url: https://database.{region}.oraclecloud.com/20160918
  description: OCI Database Service Regional Endpoint
  variables:
    region:
      default: us-ashburn-1
      description: OCI region identifier
      enum:
      - us-ashburn-1
      - us-phoenix-1
      - eu-frankfurt-1
      - uk-london-1
      - ap-tokyo-1
      - ap-mumbai-1
      - ca-toronto-1
      - ap-sydney-1
      - sa-saopaulo-1
      - ap-seoul-1
security:
- ociSignature: []
tags:
- name: Documents
  description: Document CRUD operations (get, insert, update, delete)
paths:
  /{collection}/:
    get:
      operationId: getCollection
      summary: Oracle Database Get documents from a collection
      description: Retrieves documents from the specified collection with optional filtering, pagination, and field selection. Supports Query by Example (QBE) filter specifications via the q parameter.
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      - name: limit
        in: query
        description: Maximum number of documents to return
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        description: Number of documents to skip (default 0)
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: fields
        in: query
        description: Control which fields are returned
        schema:
          type: string
          enum:
          - id
          - value
          - all
      - name: totalResults
        in: query
        description: Include total count in response (may be slow on large collections)
        schema:
          type: boolean
          default: false
      - name: fromID
        in: query
        description: Start after this key (ascending order)
        schema:
          type: string
      - name: toID
        in: query
        description: Stop before this key (descending order)
        schema:
          type: string
      - name: since
        in: query
        description: Only return documents modified after this timestamp
        schema:
          type: string
          format: date-time
      - name: until
        in: query
        description: Only return documents modified before this timestamp
        schema:
          type: string
          format: date-time
      - name: q
        in: query
        description: QBE filter specification as a JSON object
        schema:
          type: string
      responses:
        '200':
          description: Documents retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: insertDocument
      summary: Oracle Database Insert a new document
      description: Inserts a new JSON document into the collection with a server-assigned key. Returns the generated key, etag, and timestamps in the response.
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      requestBody:
        required: true
        description: JSON document to insert
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Document inserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertResponse'
        '202':
          description: Accepted for asynchronous insertion
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          description: Collection is read-only
        '501':
          description: Unsupported operation
    put:
      operationId: putDocumentNoKey
      summary: Oracle Database Insert or replace document (no key in URL)
      description: Inserts or replaces a document. Used with client-assigned keys included in the document body.
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Document replaced successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          description: Collection is read-only
  /{collection}/{key}:
    get:
      operationId: getDocument
      summary: Oracle Database Get a document by key
      description: Retrieves a single document from the collection by its unique key. Supports conditional retrieval via If-Modified-Since and If-None-Match headers.
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      - $ref: '#/components/parameters/keyParam'
      - name: If-Modified-Since
        in: header
        description: Return 304 if document has not been modified since this timestamp
        schema:
          type: string
          format: date-time
      - name: If-None-Match
        in: header
        description: Return 304 if document etag matches this value
        schema:
          type: string
      responses:
        '200':
          description: Document retrieved successfully
          content:
            application/json:
              schema:
                type: object
          headers:
            ETag:
              description: Document version tag
              schema:
                type: string
            Last-Modified:
              description: Last modification timestamp
              schema:
                type: string
                format: date-time
        '204':
          description: Document exists but has null content
        '304':
          description: Document has not been modified
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: putDocument
      summary: Oracle Database Replace or insert a document by key
      description: Replaces an existing document or inserts a new one at the specified key. Used for client-assigned keys.
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      - $ref: '#/components/parameters/keyParam'
      requestBody:
        required: true
        description: JSON document content
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Document replaced successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentMetadata'
        '201':
          description: Document inserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          description: Collection is read-only
    patch:
      operationId: patchDocument
      summary: Oracle Database Patch a document using JSON Patch
      description: Updates a document using the JSON Patch specification (RFC 6902). The request body must contain an array of patch operations.
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      - $ref: '#/components/parameters/keyParam'
      requestBody:
        required: true
        description: JSON Patch operations (RFC 6902)
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/JsonPatchOperation'
      responses:
        '200':
          description: Document patched successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          description: Collection is read-only
    delete:
      operationId: deleteDocument
      summary: Oracle Database Delete a document by key
      description: Deletes a single document from the collection by its unique key.
      tags:
      - Documents
      parameters:
      - $ref: '#/components/parameters/collectionParam'
      - $ref: '#/components/parameters/keyParam'
      responses:
        '200':
          description: Document deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          description: Collection is read-only
components:
  schemas:
    Document:
      type: object
      properties:
        id:
          type: string
          description: Unique document key
        etag:
          type: string
          description: Document version tag for optimistic concurrency
        lastModified:
          type: string
          format: date-time
          description: Last modification timestamp
        created:
          type: string
          format: date-time
          description: Creation timestamp
        value:
          type: object
          description: Document content (when fields=value or fields=all)
        mediaType:
          type: string
          description: Content type for non-JSON documents
        bytes:
          type: integer
          description: Content length for non-JSON documents
    InsertResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DocumentMetadata'
        hasMore:
          type: boolean
    DocumentMetadata:
      type: object
      properties:
        id:
          type: string
        etag:
          type: string
        lastModified:
          type: string
          format: date-time
        created:
          type: string
          format: date-time
    Link:
      type: object
      properties:
        rel:
          type: string
          description: Link relation type
        href:
          type: string
          format: uri
          description: Link URL
        mediaType:
          type: string
          description: Media type of the linked resource
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    DocumentList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        hasMore:
          type: boolean
          description: Whether more documents exist beyond this page
        limit:
          type: integer
          description: Server-imposed result limit
        offset:
          type: integer
          description: Offset of first returned result
        count:
          type: integer
          description: Number of documents in this response
        totalResults:
          type: integer
          description: Total documents in collection (only if totalResults=true)
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    JsonPatchOperation:
      type: object
      required:
      - op
      - path
      properties:
        op:
          type: string
          enum:
          - add
          - remove
          - replace
          - move
          - copy
          - test
          description: The patch operation to perform
        path:
          type: string
          description: JSON Pointer path to the target field
        value:
          description: The value to use for add, replace, or test operations
        from:
          type: string
          description: JSON Pointer path for move and copy source
  parameters:
    collectionParam:
      name: collection
      in: path
      required: true
      description: The name of the SODA collection
      schema:
        type: string
    keyParam:
      name: key
      in: path
      required: true
      description: The unique key of the document
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication required or credentials invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified collection or document was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - invalid parameter value
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ociSignature:
      type: http
      scheme: bearer
      description: OCI request signature authentication using API signing keys
externalDocs:
  description: OCI Database Service API Documentation
  url: https://docs.oracle.com/iaas/api/#/en/database/20160918/