1. SODA for REST Developer's Guide
  2. SODA for REST HTTP Operations

4 SODA for REST HTTP Operations

The SODA for REST HTTP operations are described.

  • SODA for REST HTTP Operation URIs
    A SODA for REST HTTP operation is specified by a Universal Resource Identifier (URI).
  • SODA for REST HTTP Operation Response Bodies
    If a SODA for REST HTTP operation returns information or objects, it does so in a response body.
  • GET catalog
    GET catalog gets all of the collection names for a given database schema (user account), along with information about each collection.
  • GET user collections
    GET user collections gets all or a subset of the collection names for a given database schema (user account).
  • GET JSON schema for collection
    This operation gets a JSON schema that describes the structure and type information of the JSON documents in a given collection.
  • GET actions
    GET actions gets all of the available custom actions.
  • GET collection
    GET collection gets all or a subset of objects from a collection, using parameters to specify the subset. You can page through the set of returned objects.
  • GET object
    GET object gets a specified object from a specified collection.
  • DELETE collection
    DELETE collection deletes a collection.
  • DELETE object
    DELETE object deletes a specified object from a specified collection.
  • PATCH JSON document
    PATCH JSON document replaces a specified object with an patched (edited) copy of it.
  • POST object
    POST object inserts an uploaded object into a specified collection, assigning and returning its key. The collection must use server-assigned keys.
  • POST query
    POST query gets all or a subset of objects from a collection, using a filter.
  • POST bulk insert
    POST bulk insert inserts an array of objects into a specified collection, assigning and returning their keys.
  • POST bulk delete
    POST bulk delete deletes all or a subset of objects from a specified collection, using a filter to specify the subset.
  • POST bulk update (patch)
    The POST bulk update operation updates (patches) the objects of a specified collection.
  • POST index
    POST index creates indexes on the documents in a specified collection.
  • POST unindex
    POST unindex deletes indexes on objects in a specified collection.
  • PUT collection
    PUT collection creates a collection if it does not exist.
  • PUT object
    PUT object replaces a specified object in a specified collection with an uploaded object (typically a new version). If the collection has client-assigned keys and the uploaded object is not already in the collection, then PUT inserts the uploaded object into the collection.

4.1 SODA for REST HTTP Operation URIs

A SODA for REST HTTP operation is specified by a Universal Resource Identifier (URI).

The URI has any of these forms:

/ords/database-schema/soda/[version/[metadata-catalog/[collection]]]

/ords/database-schema/soda/[version/[custom-actions/action/[collection/[key]]]]

/ords/database-schema/soda/[version/[collection/[{key|?action=action}]]]

where:

  • ords is the directory of the Oracle REST Data Services (ORDS) listener, of which SODA for REST is a component.

  • database-schema is the name of an Oracle Database schema (user account) that has been configured as an end point for SODA for REST.

  • soda is the name given to the Oracle Database JSON service when mapped as a template within ORDS.

  • version is the version number of soda.

  • custom-actions is the name for the set of possible SODA actions.

  • metadata-catalog is the name for the catalog of SODA collections.

  • collection is the name of a collection (set) of objects stored in database-schema.

  • key is a string that uniquely identifies (specifies) an object in collection.

  • action is either query, index, unindex, insert, update, delete, or truncate.

Note:

In the SODA for REST URI syntax, after the version component, you can use custom-actions, metadata-catalog, or a particular collection name. When you use custom-actions or metadata-catalog, the next segment in the URI, if there is one, is a collection name.

Because of this syntax flexibility, you cannot have a collection named either custom-actions or metadata-catalog. An error is raised if you try to create a collection with either of those names using SODA for REST.

In other SODA implementations, besides SODA for REST, nothing prevents you from creating and using a collection named custom-actions or metadata-catalog. But for possible interoperability, best practice calls for not using these names for collections.

These two syntax possibilities are equivalent:

/ords/database-schema/soda/version/custom-actions/action/collection/

/ords/database-schema/soda/version/collection/?action=action

Actions can only be used with a POST HTTP operation. (This applies to both URI syntaxes for performing actions.)

For some SODA for REST operations the path component of the URI syntax can be followed by an optional query component, which is preceded by a question mark (?). The query component is composed of one or more parameter–value pairs separated by ampersand (&) query delimiters.

In this URI, for example, the query component (?action=insert) is composed of the single parameter–value pair action=insert: 

/ords/myUser/soda/v1.0/MyCollection/?action=insert

And in this URI, the query component is composed of two parameter–value pairs, fromID=MyCollection and limit=2: 

/ords/myUser/soda/v1.0/metadata-catalog/?fromID=MyCollection&limit=2

Parent topic: SODA for REST HTTP Operations

4.2 SODA for REST HTTP Operation Response Bodies

If a SODA for REST HTTP operation returns information or objects, it does so in a response body.

For operation GET object, the response body is a single object.

Table 4-1 lists and describes fields that can appear in response bodies.

Table 4-1 Fields That Can Appear in Response Bodies

Field Description

key

String that uniquely identifies an object (typically a JSON document) in a collection.

etag

HTTP entity tag (ETag)—checksum or version.

created

Created-on time stamp.

lastModified

Last-modified time stamp.

value

Object contents (applies only to JSON object).

mediaType

HTTP Content-Type (applies only to non-JSON object).

bytes

HTTP Content-Length (applies only to non-JSON object).

items

List of one or more collections or objects that the operation found or created. This field can be followed by the fields in Table 4-2.

If an operation creates or returns objects, then its response body can have the additional fields in Table 4-2. The additional fields appear after field items.

Table 4-2 Additional Response Body Fields for Operations that Return Objects

Field Description

name

Name of collection. This field appears only in the response body of GET user collections.

properties

Properties of collection. This field appears only in the response body of GET user collections.

hasMore

true if limit was reached before available objects were exhausted, false otherwise. This field is always present.

limit

Server-imposed maximum collection (row) limit.

offset

Offset of first object returned (if known).

count

Number of objects returned. This is the only field that can appear in the response body of POST bulk delete.

totalResults

Number of objects in collection (if requested)

links

Possible final field for GET collection operation. For details, see GET collection.

Example 4-1 Response Body

This example shows the structure of a response body that returns 25 objects. The first object is a JSON object and the second is a jpeg image. The collection that contains these objects contains additional objects. 

{ "items" : [ { "id"           : "key_of_object_1",
                "etag"         : "etag_of_object_1",
                "lastModified" : "lastmodified_timestamp_of_object_1",
                "value"        : { object_1 } },
              { "id"           : "key_of_object_2",
                "etag"         : "etag_of_object_2",
                "lastModified" : "lastmodified_timestamp_of_object_2",
                "mediaType"    : "image/jpeg",
                "bytes"        : 1234
              },
              ... ],
  "hasMore" : true,
  "limit"   : 100,
  "offset"  : 50,
  "count"   : 25
  "links"   : [ ... ] }

Related Topics

Parent topic: SODA for REST HTTP Operations

4.3 GET catalog

GET catalog gets all of the collection names for a given database schema (user account), along with information about each collection.

This information includes links to collection descriptions and a link to a JSON schema that describes the structure and type information of the JSON documents in the collection.

Note:

The existence of a JSON schema requires the collection to have a JSON search index with data-guide support, which requires Oracle Database Release 12c (12.2.0.1) or later.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.3.1 URL Pattern for GET catalog

The URL pattern for GET catalog is described. 

/ords/database-schema/soda/version/metadata-catalog

Without parameters, operation GET catalog gets catalog information for all collections in database-schema.

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.

Parameter Description

limit=n

Limits number of collections to n.

fromID=collection

Starts getting with collection (inclusive).

Parent topic: GET catalog

4.3.2 Response Codes for GET catalog

The response codes for GET catalog are described.

200

Success — response body contains names and properties of collections in database schema (user account), ordered by name. For example:

{ "items": [
  { "name"       : "employees",
    "properties" : { .. .},
    "links"      : [
      { "rel" : "describes",
        "href" :
        "http://host:port/.../database-schema/soda/version/employees" },
      { "rel" : "canonical",
        "href" :
        "http://host:port/.../database-schema/soda/version/metadata-catalog/employees",
        "mediaType" : "application/json" },
      { "rel" : "alternate",
        "href" :
        "http:host:port/.../database-schema/soda/version/metadata-catalog/employees",
        "mediaType":"application/schema+json" } ] },
  { "name"       : "departments",
    "properties" : { ... },
    "links"      : [ ... ] }
  ...
  { "name"       : "regions",
    "properties" : { ... },
    "links"      : [ ... ] } ],
  "hasMore":false }

If hasMore is true, then to get the next batch of collection names specify fromID=last_returned_collection. (In the preceding example, last_returned_collection is "regions").

400

Parameter value is not valid.

401

Access is not authorized.

Related Topics

Parent topic: GET catalog

4.4 GET user collections

GET user collections gets all or a subset of the collection names for a given database schema (user account).

Related Topics

Parent topic: SODA for REST HTTP Operations

4.4.1 URL Pattern for GET user collections

The URL pattern for GET user collections is described. 

/ords/database-schema/soda/version/

Without parameters, GET user collections gets all collection names in database-schema.

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.

Parameter Description

limit=n

Limits number of listed collection names to n.

fromID=collection

Starts getting with collection (inclusive).

Parent topic: GET user collections

4.4.2 Response Codes for GET user collections

The response codes for GET user collections are described.

200

Success — response body contains names and properties of collections in database schema (user account), ordered by name. For example:

{ "items" : [
  { "name"       : "employees",
    "properties" : {...} },
  { "name"       : "departments",
    "properties" : {...} },
  ...
  { "name"       : "regions",
    "properties" : {...} } ],
  "hasMore" : false }

If hasMore is true, then to get the next batch of collection names specify fromID=last_returned_collection. (In the preceding example, last_returned_collection is "regions").

400

Parameter value is not valid.

401

Access is not authorized.

404

The database schema (user) was not found.

Parent topic: GET user collections

4.5 GET JSON schema for collection

This operation gets a JSON schema that describes the structure and type information of the JSON documents in a given collection.

Note:

The existence of a JSON schema requires the collection to have a JSON search index with data-guide support, which requires Oracle Database Release 12c (12.2.0.1) or later.

Besides a JSON schema for the collection, the operation also returns the collection metadata, as the value of field properties.

Parent topic: SODA for REST HTTP Operations

4.5.1 URL Pattern for GET JSON schema for collection

The URL pattern for getting a JSON schema for a given collection is described.

/ords/database-schema/soda/version/metadata-catalog/collection

No parameters.

Parent topic: GET JSON schema for collection

4.5.2 Response Codes for GET JSON schema for collection

The response codes for getting a JSON schema for a given collection are described.

200

Success. The response body contains a JSON schema for the collection, as the value of field schema, and the collection metadata, as the value of field properties.

For example:

{"name"       : "employees",
 "properties" : {
   "schemaName"         : "MYUSER",
   "tableName"          : "EMPLOYEES",
   "keyColumn"          : {"name"             : "ID",
                           "sqlType"          : "VARCHAR2",
                           "maxLength"        : 24,
                           "path"             : "_id",
                           "assignmentMethod" : "MONGO"},
   "contentColumn"      : {"name"       : "DOCUMENT",
                           "sqlType"    : "VARCHAR2",
                           "maxLength"  : 4000,
                           "validation" : "STRICT"},
   "versionColumn"      : {"name"   : "CHECKSUM",
                           "type"   : "String",
                           "method" : "UUID"},
   "lastModifiedColumn" : {"name"  : "LAST_MODIFIED",
                           "index" : "PEOPLE_T1"},
   "readOnly"           : false},
 "schema"     : {
   "type"       : "object",
   "properties" : {
     "dob"      : {"type"                    : "string",
                   "o:length"                : 16,
                   "o:preferred_column_name" : "dob"},
     "name"     : {"type"                    : "string",
                   "o:length"                : 16,
                   "o:preferred_column_name" : "name"},
     "email"    : {"type"                    : "array",
                   "o:length"                : 64,
                   "o:preferred_column_name" : "email",
                   "items"                   : {
                     "type"                    : "string",
                     "o:length"                : 32,
                     "o:preferred_column_name" : "scalar_string"}},
     "empno"    : {"type"                    : "number",
                   "o:length"                : 8,
                   "o:preferred_column_name" : "empno"},
     "title"    : {"type"                    : "string",
                   "o:length"                : 16,
                   "o:preferred_column_name" : "title"},
     "salary"   : {"type"                    : "number",
                   "o:length"                : 8,
                   "o:preferred_column_name" : "salary"},
     "spouse"   : {"type"                    : "null",
                   "o:length"                : 4,
                   "o:preferred_column_name" : "spouse"},
     "address"  : {"type"                    : "object",
                   "o:length"                : 128,
                   "o:preferred_column_name" : "address",
                   "properties"              : {
                     "city"   : {"type"                    : "string",
                                 "o:length"                : 16,
                                 "o:preferred_column_name" : "city"},
                     "state"  : {"type"                    : "string",
                                 "o:length"                : 2,
                                 "o:preferred_column_name" : "state"},
                     "street" : {"type"                    : "string",
                                 "o:length"                : 32,
                                 "o:preferred_column_name" : "street"}}},
     "company"  : {"type"                    : "string",
                   "o:length"                : 16,
                   "o:preferred_column_name" : "company"},
     "location" : {"type"                    : "object",
                   "o:length"                : 64,
                   "o:preferred_column_name" : "location",
                   "properties"              : {
                     "type"        : {
                       "type"                    : "string",
                       "o:length"                : 8,
                       "o:preferred_column_name" : "type"},
                     "coordinates" : {
                       "type"                    : "array",
                       "o:length"                : 32,
                       "o:preferred_column_name" : "coordinates",
                       "items"                   : {
                         "type" : "number",
                         "o:length" : 8,
                         "o:preferred_column_name" : "scalar_number"}}}},
     "department" : {"type"                    : "string",
                     "o:length"                : 16,
                     "o:preferred_column_name" : "department"}}},
 "links" : [
   {"rel"       : "describes",
    "href"      :
    "http : //host:port/.../database-schema/soda/version/employees"},
   {"rel"       : "canonical",
    "href"      :
    "http : //host:port/.../database-schema/soda/version/metadata-catalog/employees",
    "mediaType" : "application/json"},
   {"rel"       : "alternate",
    "href"      :
    "http : //host:port/.../database-schema/soda/version/metadata-catalog/employees",
    "mediaType" : "application/schema+json"}]}

401

Access is not authorized.

404

The collection does not exist.

Related Topics

Parent topic: GET JSON schema for collection

4.6 GET actions

GET actions gets all of the available custom actions.

Parent topic: SODA for REST HTTP Operations

4.6.1 URL Pattern for GET actions

The URL pattern for GET actions is described. 

/ords/database-schema/soda/version/custom-actions/

No parameters.

Parent topic: GET actions

4.7 GET collection

GET collection gets all or a subset of objects from a collection, using parameters to specify the subset. You can page through the set of returned objects.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.7.1 URL Pattern for GET collection

The URL pattern for GET collection is described. 

/ords/database-schema/soda/version/collection/

Note:

For non-JSON objects in the collection, GET collection returns, instead of document content, the media type and (if known) the size in bytes.

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.

Parameter Description

limit=n

Limits number of objects returned to a maximum of n.

offset=n

Skips n (default: 0) objects before getting the first of those returned.

fields={id|value|all}

Gets only object id fields (keys), only object value fields (content), or all fields (both key and content).

Regardless of the fields value, GET collection returns the other metadata that the collection stores for each document.

totalResults=true

Returns number of objects in collection. Note: Inefficient

fromID=key

Starts getting objects after key, in ascending order.

toID=key

Stops getting objects before key, in descending order.

after=key

Starts getting objects after key, in ascending order.

before=key

Stops getting objects before key, in descending order.

since=timestamp

Gets only objects with a lastModified time stamp later than timestamp.

until=timestamp

Gets only objects with a lastModified time stamp earlier than timestamp.

q=filter

Equivalent to a POST query action where filter is a QBE that is passed in the body of the request.

Related Topics

Parent topic: GET collection

4.7.2 Response Codes for GET collection

The response codes for GET collection are described.

200

Success—response body contains the specified objects from collection (or only their keys, if you specified fields=id). For example: 

{ "items" : [
  { "id"           : "key_of_object_1",
    "etag"         : "etag_of_object_1",
    "lastModified" : "lastmodified_timestamp_of_object_1",
    "value"        : { object_1 } },
  { "id"           : "key_of_object_2",
    "etag"         : "etag_of_object_2",
    "lastModified" : "lastmodified_timestamp_of_object_2",
    "value"        : { object_2 } },
  { "id"           : "key_of_object_3",
    "etag"         : "etag_of_object_3",
    "lastModified" : "lastmodified_timestamp_of_object_3",
    "mediaType"    : "image/jpeg",
    "bytes"        : 1234 },
  ... ],
  "hasMore" : true,
  "limit"   : 100,
  "offset"  : 50,
  "count"   : 25
  "links"   : [ ... ] }

If hasMore is true, then to get the next batch of objects repeat the operation with an appropriate parameter. For example:

  • offset=n if the response body includes the offset

  • toID=last_returned_key or before=last_returned_key if the response body includes descending=true

  • fromID=last_returned_key or after=last_returned_key if the response body does not include descending=true

400

Parameter value is not valid.

401

Access is not authorized.

404

Collection was not found.

Related Topics

Parent topic: GET collection

4.7.3 Links Array for GET collection

The links array for GET collection is described.

The existence and content of the links array depends on the mode of the GET collection operation, which is determined by its parameters.

When the links array exists, it has an element for each returned object. Each element contains links from that object to other objects. The possible links are:

  • first, which links the object to the first object in the collection

  • prev, which links the object to the previous object in the collection

  • next, which links the object to the next object in the collection

Using prev and next links, you can page through the set of returned objects.

Table 4-3 shows how GET collection parameters determine mode and the existence and content of the links array.

Table 4-3 Relationship of GET collection Parameters to Mode and Links Array

Parameter Mode Links Array

fields=id

Keys-only

Does not exist (regardless of other parameters).

offset=n

Offset

Has an element for each returned object. Each element has these links, except as noted:

  • first (except for first object)

  • prev (except for first object)

  • next (except for last object)

fromID=key

toID=key

after=key

before=key

Keyed

Has an element for each returned object. Each element has these links, except as noted:

  • prev (except for first object)

  • next (except for last object)

since=timestamp

until=timestamp

lastModified Timestamp

Does not exist.

q=QBE

 Query

Does not exist.

Related Topics

Parent topic: GET collection

4.8 GET object

GET object gets a specified object from a specified collection.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.8.1 URL Pattern for GET object

The URL pattern for GET object is described. 

/ords/database-schema/soda/version/collection/key

Parent topic: GET object

4.8.2 Request Headers for GET object

The request headers for GET object are described.

Operation GET object accepts these optional request headers:

Header Description

If-Modified-Since=timestamp

Returns response code 304 if object has not changed since timestamp. If timestamp is not in the HTTP format specified by RFC 2616 then an error is raised.

If-None-Match=etag

Returns response code 304 if the etag (object version) value you set in the header matches the etag value of the document.

See Also:

Hypertext Transfer Protocol - HTTP/1.1, RFC 2616

Parent topic: GET object

4.8.3 Response Codes for GET object

The response codes for GET object are described.

200

Success—response body contains object identified by the URL pattern.

204

Object content is null.

304

The object was not modified.

401

Access is not authorized.

404

Collection or object was not found.

Related Topics

Parent topic: GET object

4.9 DELETE collection

DELETE collection deletes a collection.

To delete all objects from a collection, but not delete the collection itself, use POST bulk delete.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.9.1 URL Pattern for DELETE collection

The URL pattern for DELETE collection is described. 

/ords/database-schema/soda/version/collection/

No parameters.

Parent topic: DELETE collection

4.9.2 Response Codes for DELETE collection

The response codes for DELETE collection are described.

200

Success—collection was deleted.

401

Access is not authorized.

404

Collection was not found.

Related Topics

Parent topic: DELETE collection

4.10 DELETE object

DELETE object deletes a specified object from a specified collection.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.10.1 URL Pattern for DELETE object

The URL pattern for DELETE object is described. 

/ords/database-schema/soda/version/collection/key

No parameters.

Parent topic: DELETE object

4.10.2 Response Codes for DELETE object

The response codes for DELETE object are described.

200

Success—object was deleted.

401

Access is not authorized.

404

Collection or bject was not found.

405

Collection is read-only.

Related Topics

Parent topic: DELETE object

4.11 PATCH JSON document

PATCH JSON document replaces a specified object with an patched (edited) copy of it.

Note:

To use operation PATCH JSON document you need Oracle Database Release 18c or later.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.11.1 URL Pattern for PATCH JSON document

The URL pattern for PATCH JSON document is described. 

/ords/database-schema/soda/version/collection/key

No parameters.

Parent topic: PATCH JSON document

4.11.2 Request Headers for PATCH JSON document

Use header Content-Type=application/json-patch+json for operation PATCH JSON document.

Parent topic: PATCH JSON document

4.11.3 Request Body for PATCH JSON document

The request body for PATCH JSON document contains a JSON Patch specification, that is, an array of objects, each of which specifies a JSON Patch step (operation). The operations are performed successively in array order.

The syntax and meaning of a JSON Patch specification, which describes changes to a JSON document, are specified in the JSON Patch standard, RFC 6902. Paths to parts of a JSON document that are referenced in a JSON Patch specification are specified using the JSON Pointer standard, RFC 6901.

See Also:

Parent topic: PATCH JSON document

4.11.4 Response Codes for PATCH JSON Document

The response codes for PATCH JSON document are described.

200

Success — document was patched (updated).

401

Access is not authorized.

404

Document or collection not found.

405

Collection is read-only.

Related Topics

Parent topic: PATCH JSON document

4.12 POST object

POST object inserts an uploaded object into a specified collection, assigning and returning its key. The collection must use server-assigned keys.

If the collection uses client-assigned keys, use PUT object.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.12.1 URL Pattern for POST object

The URL pattern for POST object is described. 

/ords/database-schema/soda/version/collection/

No parameters.

Parent topic: POST object

4.12.2 Request Body for POST object

The request body for POST object is the uploaded object to be inserted in the collection.

Parent topic: POST object

4.12.3 Response Codes for POST object

The response codes for POST object are described.

201

Success — object is in collection; response body contains server-assigned key and possibly other information. For example:

{ "items" : [ { "id"           : "key",
                "etag"         : "etag",
                "lastModified" : "last_modified_timestamp"
                "created"      : "created_timestamp" } ],
  "hasMore" : false }

202

Object was accepted and queued for asynchronous insertion; response body contains server-assigned key.

401

Access is not authorized.

405

Collection is read-only.

501

Unsupported operation (for example, no server-side key assignment).

Related Topics

Parent topic: POST object

4.13 POST query

POST query gets all or a subset of objects from a collection, using a filter.

A links section is not returned for a POST query operation, so you cannot directly do next and previous paging.

Note:

As an alternative to using POST query with a filter in the request body you can use GET collection, passing the same filter as the value of URL parameter q. For example, these two commands are equivalent, where the content of file QBE.1.json is { "User" : "TGATES" }: 

curl -X POST --data-binary @QBE.1.json -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/custom-actions/query/MyCollection/
curl -X GET  -H "Content-Type: application/json" http://localhost:8080/ords/database-schema/soda/latest/MyCollection/?q={%20%22User%22%20:%20%22TGATES%22%20}

Related Topics

Parent topic: SODA for REST HTTP Operations

4.13.1 URL Pattern for POST query

The URL pattern for POST query is described.

Query a collection using a filter, with either of these URI patterns:

/ords/database-schema/soda/version/custom-actions/query/collection
/ords/database-schema/soda/version/collection?action=query

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters. Parameters are optional, except as noted.

Parameter Description

action=query

Required, if the second syntax form is used. Specifies that the kind of action is a query.

limit=n

Limit number of returned objects to n.

offset=n

Skip n objects before returning objects.

fields={id|value|all}

Return object id (key) only, object value (content) only, or all (object key and content). Default: all

Parent topic: POST query

4.13.2 Request Body for POST query

The request body for a POST query action is a QBE (a filter-specification).

The request body cannot be empty, but it can be the empty object, {}. If it is {} then all objects in the collection are returned.

See Also:

Oracle Database Introduction to Simple Oracle Document Access (SODA) for information about SODA filter specifications.

Parent topic: POST query

4.13.3 Response Codes for POST query

The response codes for POST query are described.

200

Success—object is in collection; response body contains all objects in collection that match filter.

401

Access is not authorized.

404

The collection was not found.

Related Topics

Parent topic: POST query

4.14 POST bulk insert

POST bulk insert inserts an array of objects into a specified collection, assigning and returning their keys.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.14.1 URL Pattern for POST bulk insert

The URL pattern for POST bulk insert is described.

Insert one or more objects into a collection, using either of these URI patterns:

/ords/database-schema/soda/version/custom-actions/insert/collection
/ords/database-schema/soda/version/collection?action=insert

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.

Parameter Description

action=insert

Required, if the second syntax form is used. Specifies that the kind of action is a bulk insert.

Parent topic: POST bulk insert

4.14.2 Request Body for POST bulk insert

The request body for POST bulk insert is an array of objects.

Parent topic: POST bulk insert

4.14.3 Response Codes for POST bulk insert

The response codes for POST bulk insert are described.

200

Success — response body contains an array with the assigned keys for inserted objects. For example:

{ "items" : [ { "id"           : "12345678",
                "etag"         : "...",
                "lastModified" : "..."
                "created"      : "..." },
              { "id"           : "23456789",
                "etag"         : "...",
                "lastModified" : "..."
                "created"      : "..." } ],
  "hasMore" : false }

401

Access is not authorized.

404

Collection was not found.

405

Collection is read-only.

Related Topics

Parent topic: POST bulk insert

4.15 POST bulk delete

POST bulk delete deletes all or a subset of objects from a specified collection, using a filter to specify the subset.

Note:

If you delete all objects from a collection, the empty collection continues to exist. To delete the collection itself, use DELETE collection.

There are two bulk-delete operations, with the HTTP POST actions delete and truncate, respectively. Action delete is more general; you can use it to delete some or all objects in a collection. Action truncate always deletes all objects from the collection. Action delete is driven by a filter, which selects the objects to delete.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.15.1 URL Pattern for POST bulk delete

The URL pattern for POST bulk delete is described.

Delete some or all objects from a collection, as determined by a filter using either of these URI patterns:

/ords/database-schema/soda/version/custom-actions/delete/collection

/ords/database-schema/soda/version/collection?action=delete

Delete all objects from a collection (truncate the collection) using either of these URI patterns: 

/ords/database-schema/soda/version/custom-actions/truncate/collection

/ords/database-schema/soda/version/collection?action=truncate

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.

Action Description

delete

Required. Specifies the deletion of all or a subset of objects from collection, using a filter to specify the subset. (The filter must be present, but it can be the empty object, {}.)

truncate

Required. Specifies the deletion of all objects from collection. Does not use a filter.

WARNING:

If you specify delete as the action, and you use the empty object, {}, as the filter specification, then the operation deletes all objects from the collection.

Parent topic: POST bulk delete

4.15.2 Request Body for POST bulk delete (Optional)

If the action is delete (not truncate) then the request body contains the filter (QBE) that specifies which documents to delete from the collection.

See Also:

Oracle Database Introduction to Simple Oracle Document Access (SODA) for information about SODA filter specifications

Parent topic: POST bulk delete

4.15.3 Response Codes for POST bulk delete

The response codes for POST bulk delete are described.

200

Success — response body contains the number of deleted objects, as the value of fields count and itemsDeleted. For example: 

{ "count"       : 42,
  "itemsDeleted : 42 }

401

Access is not authorized.

404

Collection not found.

405

Collection is read-only.

Related Topics

Parent topic: POST bulk delete

4.16 POST bulk update (patch)

The POST bulk update operation updates (patches) the objects of a specified collection.

Objects that match a QBE are patched according to a JSON Patch specification.

Note:

To use operation POST bulk update you need Oracle Database Release 18c or later.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.16.1 URL Pattern for POST bulk update (patch)

The URL pattern for POST bulk update is described.

Update one or more objects of a collection, using either of these URI patterns:

/ords/database-schema/soda/version/custom-actions/update/collection
/ords/database-schema/soda/version/collection?action=update

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.

Parameter Description

action=update

Required, if the second syntax form is used. Specifies that the kind of action is a bulk update.

Parent topic: POST bulk update (patch)

4.16.2 Request Body for POST bulk update (patch)

The request body for POST bulk update is an array of objects.

The request body is a QBE that has a $patch field whose value is a JSON Patch specification, as in Example 3-10.

Parent topic: POST bulk update (patch)

4.16.3 Response Codes for POST bulk update (patch)

The response codes for POST bulk update are described.

200

Success — response body contains the number of objects updated, as the value of fields count and itemsUpdated. For example: 

{ "count"       : 42,
  "itemsUpdated : 42

401

Access is not authorized.

405

Not allowed: collection is read-only.

Related Topics

Parent topic: POST bulk update (patch)

4.17 POST index

POST index creates indexes on the documents in a specified collection.

Note:

To create an index with SODA you need Oracle Database Release 12c (12.2.0.1) or later. But to create a B-tree index that for a DATE or TIMESTAMP value you need Oracle Database Release 18c (18.1) or later.

Parent topic: SODA for REST HTTP Operations

4.17.1 URL Pattern for POST index

The URL pattern for POST index is described.

Index one or more objects of a collection, using either of these URI patterns:

/ords/database-schema/soda/version/custom-actions/index/collection
/ords/database-schema/soda/version/collection?action=index

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.

Parameter Description

action=index

Required, if the second syntax form is used. Specifies that the action is an indexing action.

Parent topic: POST index

4.17.2 Request Body for POST index

The request body for POST index is a SODA index specification.

A SODA index specification is a JSON object that specifies a particular kind of Oracle Database index, which is used for operations on JSON documents. You can specify these kinds of index:

  • B-tree: Used to index scalar JSON values.

  • Spatial: Used to index GeoJSON geographic data.

  • Search: Used for one or both of the following:

    • Ad hoc structural queries or full-text searches

    • JSON data guide

Note:

To create a data guide-enabled JSON search index, or to data guide-enable an existing JSON search index, you need database privilege CTXAPP and Oracle Database Release 12c (12.2.0.1) or later.

See Also:

Parent topic: POST index

4.17.3 Response Codes for POST index

The response codes for POST index are described.

200

Success.

401

Access is not authorized.

404

Collection was not found.

Related Topics

Parent topic: POST index

4.18 POST unindex

POST unindex deletes indexes on objects in a specified collection.

Parent topic: SODA for REST HTTP Operations

4.18.1 URL Pattern for POST unindex

The URL pattern for POST unindex is described.

Unindex one or more objects of a collection, using either of these URI patterns:

/ords/database-schema/soda/version/custom-actions/unindex/collection
/ords/database-schema/soda/version/collection?action=unindex

You can include one or more parameter–value pairs at the end of the URL, preceded by a question mark (?) and separated by ampersand (&) query delimiters.

Parameter Description

action=unindex

Required, if the second syntax form is used. Specifies that the action is an unindexing action.

Parent topic: POST unindex

4.18.2 Request Body for POST unindex

The request body for POST unindex is a SODA index specification. But only the name of the index need be specified — the rest of the index specification is ignored.

See Also:

Oracle Database Introduction to Simple Oracle Document Access (SODA) for information about SODA index specifications

Parent topic: POST unindex

4.18.3 Response Codes for POST unindex

The response codes for POST unindex are described.

200

Success.

401

Access is not authorized.

404

Collection was not found.

Related Topics

Parent topic: POST unindex

4.19 PUT collection

PUT collection creates a collection if it does not exist.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.19.1 URL Pattern for PUT collection

The URL pattern for PUT collection is described. 

/ords/database-schema/soda/version/collection

No parameters.

Parent topic: PUT collection

4.19.2 Request Body for PUT collection (Optional)

The request body for PUT collection optionally contains a collection specification, which defines the metadata of the collection that is created. (If no specification is present then the default metadata is used.)

Parent topic: PUT collection

4.19.3 Response Codes for PUT collection

The response codes for PUT collection are described.

200

Collection with the same name and properties already exists.

201

Success—collection was created.

401

Access is not authorized.

Related Topics

Parent topic: PUT collection

4.20 PUT object

PUT object replaces a specified object in a specified collection with an uploaded object (typically a new version). If the collection has client-assigned keys and the uploaded object is not already in the collection, then PUT inserts the uploaded object into the collection.

Related Topics

Parent topic: SODA for REST HTTP Operations

4.20.1 URL Pattern for PUT object

The URL pattern for PUT object is described.

There are two forms of the URL pattern:

  • Pattern for a collection that has client-assigned keys:

    /ords/database-schema/soda/version/collection/key

  • Pattern for a collection that has system-assigned keys:

    /ords/database-schema/soda/version/collection/

No parameters.

Parent topic: PUT object

4.20.2 Request Body for PUT object

The request body for PUT object is the uploaded object.

Parent topic: PUT object

4.20.3 Response Codes for PUT object

The response codes for PUT object are described.

200

Success—object was replaced.

401

Access is not authorized.

405

Collection is read-only.

Related Topics

Parent topic: PUT object