The SODA for REST HTTP operations are described.
Table 4-1 summarizes the HTTP operations that SODA for REST provides. For complete descriptions of the operations, click the links in the left column.
Table 4-1 SODA for REST HTTP Operations
Operation | Description |
---|---|
Gets some or all collection names in a schema. |
|
Gets all or a subset of objects from a collection, using parameters to specify the subset. You can page through the return set. |
|
Gets a specified object from a collection. |
|
Creates a collection if it does not exist. |
|
Replaces a specified object 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 |
|
Deletes a collection. |
|
Deletes a specified object from a collection. |
|
Puts an uploaded object in a specified collection, assigning and returning its key. Collection must use server-assigned keys. |
|
Gets all or a subset of objects from a collection, using a filter to specify the subset. You cannot page through the return set. |
|
Inserts an array of objects into a specified collection, assigning and returning their keys. |
|
Deletes all or a subset of objects from a collection. |
A SODA for REST HTTP operation is specified by a Universal Resource Identifier (URI).
The URI has this form:
/ords/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.
schema
is the name of an Oracle Database schema 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
.
collection
is the name of a set of objects stored in schema
.
Typically, an object is a JSON document, but it can be a Multipurpose Internet Mail Extensions (MIME) type (for example, image, audio, or video).
A JSON document is represented as textual JSON.
Typically, an application uses a collection to hold all instances of a particular type of object. Thus, a collection is roughly analogous to a table in a relational database. One column stores keys and another column stores content.
key
is a string that uniquely identifies an object in collection
.
A specified object is specified by its key.
action
is either query
, index
, unindex
, insert
, update
, or delete
.
If a SODA for REST HTTP operation returns information or objects, it does so in a response body.
For the operation GET object, the response body is a single object.
Table 4-2 lists and describes fields that can appear in response bodies.
Table 4-2 Fields That Can Appear in Response Bodies
Field | Description |
---|---|
|
String that uniquely identifies an object (typically a JSON document) in a collection. |
|
HTTP entity tag (ETag)—checksum or version. |
|
Created-on time stamp. |
|
Last-modified time stamp. |
|
Object contents (applies only to JSON object). |
|
HTTP Content-Type (applies only to non-JSON object). |
|
HTTP Content-Length (applies only to non-JSON object). |
|
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-3. |
If an operation creates or returns objects, then its response body can have the additional fields in Table 4-3. The additional fields appear after field items
.
Table 4-3 Additional Response Body Fields for Operations that Return Objects
Field | Description |
---|---|
|
Name of collection. This field appears only in the response body of GET schema. |
|
Properties of collection. This field appears only in the response body of GET schema. |
|
|
|
Server-imposed maximum collection (row) limit. |
|
Offset of first object returned (if known). |
|
Number of objects returned. This is the only field that can appear in the response body of POST bulk delete. |
|
Number of objects in collection (if requested) |
|
Possible final field for |
Example 4-1 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.
Example 4-1 Response Body
{ "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" : [ ... ] }
GET
schema gets all or a subset of collection names in a schema.
See Also:
The URL pattern for GET
schema is described.
/ords/schema/soda/version/
Without parameters, GET schema
gets all collection names in schema
.
Parameter | Description |
---|---|
|
Limits number of listed collection names to |
|
Starts getting with |
The response codes for GET
schema are described.
200
Success—response body contains names and properties of collections in schema, ordered by name. For example:
{ "items" : [ {"name" : "employees", "properties" : {...} }, {"name" : "departments", "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"
).
404
Either the schema was not found or access is not authorized.
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.
See Also:
POST query, which gets all or a subset of objects from a collection, using a filter instead of parameters. You cannot page through the set of returned objects.
The URL pattern for GET
collection is described.
/ords/schema/soda/version/collection/
Without parameters, GET collection
gets all objects (both key and content) from collection
and does not return the number of objects in collection
.
Note:
For non-JSON objects in the collection, GET collection
returns, instead of content, media type and (if known) size in bytes.
Parameter | Description |
---|---|
|
Limits number of objects to |
|
Skips |
|
Gets only object Regardless of the |
|
Returns number of objects in collection. Note: Inefficient |
|
Starts getting objects after |
|
Stops getting objects before |
|
Starts getting objects after |
|
Stops getting objects before |
|
Gets only objects with time stamp later than |
|
Gets only objects with time stamp earlier than |
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
For information about links
, see Links Array for GET collection.
401
Read access to collection is not authorized.
404
Collection was not found.
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-4 shows how GET collection
parameters determine mode and the existence and content of the links
array.
Table 4-4 Relationship of GET collection Parameters to Mode and Links Array
Parameter | Mode | Links Array |
---|---|---|
|
Keys-only |
Does not exist (regardless of other parameters). |
|
Offset |
Has an element for each returned object. Each element has these links, except as noted:
|
|
Keyed |
Has an element for each returned object. Each element has these links, except as noted:
|
|
Timestamp |
Does not exist. |
GET
object gets a specified object from a specified collection.
See Also:
The URL pattern for GET
object is described.
/ords/schema/soda/version/collection/key/
No parameters.
The request headers for GET
object are described.
Operation GET object
accepts these optional request headers:
Header | Description |
---|---|
|
Returns response code 304 if object has not changed since |
|
Returns response code 304 if 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
Either object was not modified since modification date or checksum matches object etag
(see Request Headers for GET object).
401
Read access to collection or object is not authorized.
404
Collection or object was not found.
PUT
collection creates a collection if it does not exist.
See Also:
The URL pattern for PUT
collection is described.
/ords/schema/soda/version/collection/
No parameters.
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.
See Also:
The URL pattern for PUT
object is described.
/ords/schema/soda/version/collection/key/
No parameters.
DELETE
collection deletes a collection.
To delete all objects from a collection, but not delete the collection itself, use POST bulk delete.
See Also:
The URL pattern for DELETE
collection is described.
/ords/schema/soda/version/collection/
No parameters.
DELETE
object deletes a specified object from a specified collection.
See Also:
The URL pattern for DELETE
object is described.
/ords/schema/soda/version/collection/key/
No parameters.
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. For information about key assignment methods, see Key Assignment Method.
See Also:
The URL pattern for POST
object is described.
/ords/schema/soda/version/collection/
No parameters.
The request body for POST
object is the uploaded object to be inserted in the collection.
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" : "timestamp" "created" : "timestamp" } ], "hasMore" : false }
202
Object was accepted and queued for asynchronous insertion; response body contains server-assigned key.
401
Inserting into collection is not authorized.
405
Collection is read-only.
501
Unsupported operation (for example, no server-side key assignment).
POST
query gets all or a subset of objects from a collection, using a filter to specify the subset. You cannot page through the set of returned objects.
See Also:
GET collection, which gets all objects, or a subset of these, from a collection, using parameters instead of a filter. You can page through the set of returned objects.
Using a Filter Specification to Select Documents From a Collection
The URL pattern for POST
query is described.
/ords/schema/soda/version/collection?action=query
Parameters are optional except as noted.
Parameter | Description |
---|---|
|
Required. Specifies kind of action. |
|
Limit number of returned objects to |
|
Skip |
|
Return object |
If you omit the filter specification object from the request body of POST
query then the operation gets all objects in the collection.
See Also:
Oracle Database Introduction to Simple Oracle Document Access (SODA) for information about SODA filter specifications.
POST
array insert inserts an array of objects into a specified collection, assigning and returning their keys.
The URL pattern for POST
array insert is described.
/ords/schema/soda/version/collection?action=insert
Parameter | Description |
---|---|
|
Required. Specifies kind of action. |
The request body for POST
array insert is an array of objects.
Array of objects.
The response codes for POST
array 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
Inserting into collection is not authorized.
404
Collection was not found.
405
Collection is read-only.
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 the collection, the empty collection continues to exist. To delete the collection itself, use DELETE collection.
The URL pattern for POST
bulk delete is described.
Either of the following:
/ords/schema/soda/version/collection?action=delete /ords/schema/soda/version/collection?action=truncate
Parameter | Description |
---|---|
|
Required. Specifies the deletion of all or a subset of objects from |
|
Required. Specifies the deletion of all objects from |
WARNING:
If you specify action=delete
and omit the filter specification, or if the filter specification is empty, then the operation deletes all objects from the collection.
See Oracle Database SODA for Java Developer's Guide for information about SODA filter specifications.