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.