CRUD Tasks

4 CRUD Tasks

You can access business object using standard HTTP request methods, including GET, POST, PATCH, and DELETE.

Topics

Retrieving Business Objects

REST APIs support the GET method on REST resources to retrieve a resource or nested resource, page a resource, filter a resource collection with a query, or sort a resource collection.

REST APIs support the following GET method use cases:

Fetching a resource collection payload.
Fetching a resource collection payload with a subset of resource items.
Fetching a resource item payload.
Fetching a paged resource collection.
Fetching a sorted resource collection.
Fetching a nested child resource item payload.
Fetching data only in a resource item payload.
Filtering a resource item payload with query parameters.

Fetching a Business Object

REST APIs support fetching a resource collection without filtering items.

The following sample fetches the Department resource collection and all five items of the collection.

Request

URL

<base_url>/Department
HTTP Method

GET
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourcecollection+json

Payload

{
  "items" : [ {
    "DepartmentId" : 10,
    "DepartmentName" : "Administration",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/10",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/10/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 20,
    "DepartmentName" : "Marketing",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/20",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/20/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 30,
    "DepartmentName" : "Purchasing",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/30",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/30/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 40,
    "DepartmentName" : "Human Resources",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/40",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/40/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 50,
    "DepartmentName" : "Shipping",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/50",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/50/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  } ],
  "count" : 5,
  "hasMore" : false,
  "limit" : 5,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department",
    "kind" : "collection"
  } ]
}

Fetching a Business Object with a Subset of Items

REST APIs support fetching a resource collection with a subset of items.

The payload structure of nested child resource differs depending on the REST API framework version that has been registered for the request. For details about the REST API framework versions, see Understanding REST API Framework Version Support.

The following samples are based on different versions of the REST API framework, which reflect the response payload structure change supported in REST API framework version 3 (and later). In both framework scenarios, the samples fetch the Employee resource as a child of the Department resource.

REST API Framework Version 3 (and later)

Starting with version 3 of the REST API framework, the REST API returns a nested child resource in the response payload as a resource collection, instead of as an array of resource items. This functionality, available in framework version 3 (and later), allows web applications to make a request for additional records after determining how many items were left unfetched in the initial request. The attributes hasMore and count on the child resource indicate whether more items may be returned from the resource collection. For details about using the pagination attributes from the response payload when you opt into REST API framework version 3, see Paging a Business Object.

The following sample illustrates functionality for REST API framework version 3 (and later). The response payload represents the nested child resource as a resource collection, where the collection object includes the hasMore and count attributes. A link is provided should it be necessary to query the child resource for additional resource items. In this sample, the response payload shows the hasMore attribute is false, suggesting that no items remain unfetched on the Employee child resource for either department 10 or department 20.

Request Made With Framework Version 3

URL

<base_url>/Department?fields=DepartmentId;Employee:FirstName&onlyData=true
HTTP Method

GET
Query Parameters

fields

This parameter filters resource attributes so that only the specified attributes are returned. The parameter value is a comma-separated list of attribute names when filtering a single resource collection. Example: ?fields=FirstName,LastName. When filtering multiple resources, the resource names are followed by a colon and the comma-separated attribute names list with a semi-colon separating each resource filter list. Example: ?fields=Employee:FirstName;Employee.JobHistory:JobId. Note that dot notation allows access to nested resources. This parameter cannot be combined with expand query parameter. If both are provided, only fields will be considered.

onlyData

This parameter filters the resource item payload to contain only data (no links section, for example).
Content-Type

none
Payload

none

Response Made With Framework Version 3

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourcecollection+json

Payload

{
    "items" : [ {
        "DepartmentId" : 10,
        "Employee" : {
             "items" : [ {
                {
                    "FirstName" : "Jennifer"
                   }
          }  ],
          "count" : 1,
          "hasMore" : false,
          "limit" : 25,
          "offset" : 0,
          "links" : [ {
              "rel" : "self",
              "href" : "<base_url>/Department/10/child/Employee",
              "name" : "Employee",
              "kind" : "collection"
        }, ]
     }, {
        "DepartmentId" : 20,
            "Employee" : {
                "items" : [ {
                   {
                       "FirstName" : "Michael"
                   },
                   {
                       "FirstName" : "Pat"
                   }
          }  ],
          "count" : 2,
          "hasMore" : false,
          "limit" : 25,
          "offset" : 0,
          "links" : [ {
              "rel" : "self",
              "href" : "<base_url>/Department/20/child/Employee",
              "name" : "Employee",
              "kind" : "collection"
        }, ]
     }, {
      ...
    ],
    "count" : 25,
    "hasMore" : true,
    "limit" : 25,
    "offset" : 0,
    "links" : [
        {
            "rel" : "self",
            "href" : "<base_url>/Department",
            "name" : "Department",
            "kind" : "collection"
        }
    ]

REST API Framework Version 1 or Version 2

Version 1 and version 2 of the REST API framework return the nested child resource expanded in the response payload as an array of resource items. If the resource collection being fetched is large, several requests will be required to fetch all items.

The following samples fetch the attribute values of the Department and Employee collections. The query parameter fields ensures the response payload contains only the specified attributes. Note that a GET request may return no values for any resource in the URL that does not specify an attribute value.

The first request (URL 1) fetches the items for employee 101. The query parameter fields ensures the response payload contains only the specified attributes: FirstName, LastName, and Email.

The second request (URL 2) fetches the department DepartmentId and the FirstName item for employees of each department. The query parameter onlyData filters the response to hide child links.

The third request (URL 3) fetches the department DepartmentId, the FirstName item for employees of each department, and the JobId history for each employee. The query parameter onlyData again filters the response to hide child links.

Request 1 Made With Framework Version 1 or 2

URL 1

<base_url>/Employee/101?fields=FirstName,LastName,Email
HTTP Method

GET
Query Parameters

fields

This parameter filters resource attributes so that only the specified attributes are returned. The parameter value is a comma-separated list of attribute names when filtering a single resource collection. Example: ?fields=FirstName,LastName. When filtering multiple resources, the resource names are followed by a colon and the comma-separated attribute names list with a semi-colon separating each resource filter list. Example: ?fields=Employee:FirstName;Employee.JobHistory:JobId. Note that dot notation allows access to nested resources. This parameter cannot be combined with expand query parameter. If both are provided, only fields will be considered.
Content-Type

none
Payload

none

Response 1 From Framework Version 1 or 2

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload 1

{
  "FirstName" : "Neena",
  "LastName" : "Smith",
  "Email" : "NSMITH",
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Employee/101",
    "name" : "Employee",
    "kind" : "item"
  } ]
}

Request 2 Made With Framework Version 1 or 2

URL 2

<base_url>/Department?fields=DepartmentId;Employee:FirstName&onlyData=true
HTTP Method

GET
Query Parameters

fields

This parameter filters resource attributes so that only the specified attributes are returned. The parameter value is a comma-separated list of attribute names when filtering a single resource collection. Example: ?fields=FirstName,LastName. When filtering multiple resources, the resource names are followed by a colon and the comma-separated attribute names list with a semi-colon separating each resource filter list. Example: ?fields=Employee:FirstName;Employee.JobHistory:JobId. Note that dot notation allows access to nested resources. This parameter cannot be combined with expand query parameter. If both are provided, only fields will be considered.

onlyData

This parameter filters the resource item payload to contain only data (no links section, for example).
Content-Type

none
Payload

none

Response 2 From Framework Version 1 or 2

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourcecollection+json

Payload 2

{
    "items" : [
 
        {
            "DepartmentId" : 10,
            "Employee" : [
                {
                    "FirstName" : "Jennifer"
                }
            ]
        },
        {
            "DepartmentId" : 20,
            "Employee" : [
                {
                    "FirstName" : "Michael"
                },
                {
                    "FirstName" : "Pat"
                }
            ]
        },
        {
            "DepartmentId" : 30,
            "Employee" : [
                {
                    "FirstName" : "Den"
                },
                {
                    "FirstName" : "Alexander"
                },
                {
                    "FirstName" : "Shelli"
                },
                {
                    "FirstName" : "Sigal"
                },
                {
                    "FirstName" : "Guy"
                },
                {
                    "FirstName" : "Karen"
                }
            ]
        },
        {
            "DepartmentId" : 40,
            "Employee" : [
                {
                    "FirstName" : "Susan"
                }
            ]
        },
      ...
    ],
    "count" : 25,
    "hasMore" : true,
    "limit" : 25,
    "offset" : 0,
    "links" : [
        {
            "rel" : "self",
            "href" : "<base_url>/Department",
            "name" : "Department",
            "kind" : "collection"
        }
    ]

Request 3 Made With Framework Version 1 or 2

URL 3

<base_url>/Department?fields=DepartmentId;Employee:FirstName;Employee.JobHistory:JobId&onlyData=true
HTTP Method

GET
Query Parameters

fields

This parameter filters resource attributes so that only the specified attributes are returned. The parameter value is a comma-separated list of attribute names when filtering a single resource collection. Example: ?fields=FirstName,LastName. When filtering multiple resources, the resource names are followed by a colon and the comma-separated attribute names list with a semi-colon separating each resource filter list. Example: ?fields=Employee:FirstName;Employee.JobHistory:JobId. Note that dot notation allows access to nested resources. This parameter cannot be combined with expand query parameter. If both are provided, only fields will be considered.

onlyData

This parameter filters the resource item payload to contain only data (no links section, for example).
Content-Type

none
Payload

none

Response 3 From Framework Version 1 or 2

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourcecollection+json

Payload 3

{
    "items" : [
 
        {
            "DepartmentId" : 10,
            "Employee\" : [
                {
                    "FirstName" : "Jennifer",
                    "JobHistory" : [
                        {
                            "JobId" : "AD_ASST"
                        },
                        {
                            "JobId" : "AC_ACCOUNT"
                        }
                    ]
                }
            ]
        },
        {
            "DepartmentId" : 20,
            "Employee" : [
                {
                    "FirstName" : "Michael",
                    "JobHistory" : [
                        {
                            "JobId" : "MK_REP"
                        }
                    ]
                },
                {
                    "FirstName" : "Pat",
                    "JobHistory" : [
                        {
                            "JobId" : "AD_ASST"
                        },
                        {
                            "JobId" : "AC_ACCOUNT"
                        }
                    ]
                }
            ]
        },
        {
            "DepartmentId" : 30,
            "Employee" : [
                {
                    "FirstName" : "Den",
                    "JobHistory" : [
                        {
                            "JobId" : "ST_CLERK"
                        }
                    ]
                },
                {
                    "FirstName" : "Alexander",
                    "JobHistory" : [
                        {
                            "JobId" : "AD_ASST"
                        },
                        {
                            "JobId" : "AC_ACCOUNT"
                        }
                    ]
                },
                {
                    "FirstName" : "Shelli",
                    "JobHistory" : [
                        {
                            "JobId" : "AD_ASST"
                        },
                        {
                            "JobId" : "AC_ACCOUNT"
                        }
                    ]
 
            ]
          ...
    ],
    "count" : 25,
    "hasMore" : false,
    "limit" : 25,
    "offset" : 0,
    "links" : [
        {
            "rel" : "self",
            "href" : "<base_url>/Department",
            "name" : "Department",
            "kind" : "collection"
        }
    ]
}

Fetching a Business Object Item

REST APIs support fetching a resource item.

The following sample fetches Department resource item 50. The response includes a link to the nested child Employee resource.

Request

URL

<base_url>/Department/50
HTTP Method

GET
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload

{
  "DepartmentId" : 50,
  "DepartmentName" : "Shipping",
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department/50",
    "name" : "Department",
    "kind" : "item"
  }, {
    "rel" : "child",
    "href" : "<base_url>/Department/50/child/Employee",
    "name" : "Employee",
    "kind" : "collection"
  } ]
}

Paging a Business Object

REST APIs support retrieving resource collections with pagination to display the resource items in sets. Paging is performed using the following URI query parameters:

limit restricts the number of resources returned inside the resource collection. If the limit exceeds the resource count, then the framework will return all available resources. The value is the maximum number of resources to be returned.
offset defines a zero-based index into the collection (where 0 is the first position). The index identifies the starting position of the resource collection. If offset exceeds the resource count, then no resources are returned.

In the following sample, where a Department resource collection has five items, the first request (URL1) retrieves two items (at index 0 and 1), and because offset is omitted, the starting position of the response is the first item. To display another set of resource items, a second request (URL2) may be made with an offset of 2 to correspond to the third item and a limit of 2 to retrieve only two more items (at index 2 and 3), and the last request (URL3) with an offset of 4 returns the last item of the five item resource collection (at index 4).

Each time a new set of resource items is retrieved, the hasMore attribute of the response indicates whether more items may be returned from the collection. In this example, because the collection contains only five items, the response for URL3 shows hasMore set to false, indicating that the last set of items had been retrieved.

Note that when the limit parameter is omitted from the paging URL, the REST API assumes a limit of 25 (as determined by the default RangeSize value on the business object definition). In this case, up to twenty-five items will be returned with each request. For this reason, it is a best practice when paging through a collection to always include the limit query parameter to ensure only the desired number of resource items are returned and not more.

Requests

URL 1

<base_url>/Department?limit=2
URL 2

<base_url>/Department?offset=2&limit=2
URL 3

<base_url>/Department?offset=4&limit=2
HTTP Method

GET
Query Parameters

limit

This parameter is an integer value that restricts the number of resource returned inside the resource collection. If the limit exceeds the resource total results, then the available resources will be returned.

offset

This parameter is an integer value that defines the starting position of the resource collection. The default (0) specifies the first position. If the offset exceeds the resource count, then no resources are returned.
Content-Type

none
Payload

none

Responses

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourcecollection+json

Payload 1

{
  "items" : [ {
    "DepartmentId" : 10,
    "DepartmentName" : "Administration",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/10",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/10/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 20,
    "DepartmentName" : "Marketing",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/20",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/20/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  } ],
  "count" : 2,
  "hasMore" : true,
  "limit" : 2,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department",
    "kind" : "collection"
  } ]
}

Payload 2

{
  "items" : [ {
    "DepartmentId" : 30,
    "DepartmentName" : "Purchasing",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/30",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/30/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 40,
    "DepartmentName" : "Human Resources",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/40",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/40/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  } ],
  "count" : 2,
  "hasMore" : true,
  "limit" : 2,
  "offset" : 2,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department",
    "kind" : "collection"
  } ]
}

Payload 3

{
  "items" : [ {
    "DepartmentId" : 50,
    "DepartmentName" : "Shipping",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/50",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/50/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  } ],
  "count" : 1
  "hasMore" : false,
  "limit" : 2
  "offset" : 4,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department,
    "kind" : "collection"
  } ]
}

Sorting a Business Object

REST APIs support sorting the fetched resource items.

Sorting is performed using the orderBy query string parameter in combination with one or more attribute names. The following optional sort order flags may be associated with each attribute:

asc sorts in ascending order. (Default)
desc sorts in descending order.

The orderBy query string parameter format is:

<orderBy_attribute1_name>:<(asc/desc)>, <orderBy_attribute2_name>:<(asc/desc)>

Example: attribute1:desc,attribute2

The following sample (URL1) fetches the Department collection sorted by the DepartmentName attribute. The second sample (URL2) fetches the child Employee collection sorted by the salary attribute. Since the sort order flag is not specified for either request sample, the response is ascending order.

Request

URL 1

<base_url>/Department?orderBy=DepartmentName
URL 2

<base_url>/Department/50/child/Employee?orderBy=Salary
HTTP Method

GET
Query Parameter

orderBy

This parameter orders a resource collection based on the specified attributes. The parameter value is a comma-separated string of attribute names, each optionally followed by a colon and asc or desc. Specify asc for ascending and desc for descending. The default value is asc. For example, ?orderBy=attr1:asc,attr2:desc.
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload 1

{
  "items" : [ {
    "DepartmentId" : 10,
    "DepartmentName" : "Administration",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/10",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/10/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 40,
    "DepartmentName" : "Human Resources",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/40",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/40/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 20,
    "DepartmentName" : "Marketing",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/20",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/20/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 30,
    "DepartmentName" : "Purchasing",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/30",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/30/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 50,
    "DepartmentName" : "Shipping",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/50",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/50/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  } ],
  "count" : 5,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department",
    "kind" : "collection"
  } ]
}

Payload 2

{
  "items" : [ {
    "EmployeeId" : 132,
    "FirstName" : "TJ",
    "LastName" : "Olson",
    "Email" : "TJOLSON",
    "JobId" : "ST_CLERK",
    "DepartmentId" : 50,
    "Salary" : 2100,
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Employee/132",
      "name" : "Employee",
      "kind" : "item"
    } ]
  }, {
    "EmployeeId" : 136,
    "FirstName" : "Hazel",
    "LastName" : "Philtanker",
    "Email" : "HPHILTAN",
    "JobId" : "ST_CLERK",
    "DepartmentId" : 50,
    "Salary" : 3100,
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Employee/136",
      "name" : "Employee",
      "kind" : "item"
    } ]
  } ],
  "count" : 2,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Employee",
    "name" : "Employee",
    "kind" : "collection"
  } ]
}

Fetching a Child Business Object

REST APIs support retrieving a nested child resource collection.

The payload structure of a nested child resource collection differs depending on the Oracle Business Object REST API framework version that has been registered for the web application. For details about the Oracle Business Object REST API framework versions, see Working with REST API Framework Versions.

The following samples are based on two different versions of the Employee resource. The URL samples showing resource 1.0 reflect a response payload structure supported by REST API framework versions 1 and 2. While the URL samples showing resource 2.0, reflect the response payload structure supported in REST API framework version 3 (and later). In both framework scenarios, the samples fetch the Employee resource nested within the Department resource.

REST API Framework Version 3 (and later)

Starting with version 3 of the REST API framework, the REST API returns a nested child resource in the response payload as a resource collection, instead of as an array of resource items. This functionality, available in framework version 3 (and later), allows web applications to make a request for additional records after determining how many items were left unfetched in the initial request. The attributes hasMore and count on the nested resource indicate whether more items may be returned from the resource collection. For details about using the pagination attributes from the response payload when you opt into REST API framework version 3, see Paging a Business Object.

The following sample illustrates functionality for REST API framework version 3 (and later). The response payload represents the nested child resource as a resource collection, where the collection object includes the hasMore and count attributes. A link is provided should it be necessary to query the nested resource for additional resource items. In this sample, items of the Employee nested resource are fetched with a count of 3 in the payload. The response payload shows the hasMore attribute is false, suggesting that no items remain unfetched.

Request Made With Framework Version 3

URL

<base_url>/Department/50?expand=Employee
HTTP Method

GET
Query Parameter

expand

When this parameter is provided in combination with REST API framework version 2 or later, the specified children are included in the resource payload (instead of just a link). The value of this query parameter is all or <accessor1>,<accessor2>,... When all is specified, only the top-level children will be included in the resource payload. More than one child can be specified using comma as a separator. Example: ?expand=Employee,Localization. Nested children can also be provided following the format "Child.NestedChild" (Example: ?expand=Employee.Manager). If a nested child is provided (Example: Employee.Manager), the missing children will be processed implicitly. For example, ?expand=Employee.Manager is the same as ?expand=Employee,Employee.Manager (which will expand Employee and Manager).

Note the expand parameter cannot be combined with the fields parameter. If both parameters are provided, only fields will be considered.
Content-Type

none
Payload

none

Response From Framework Version 3

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload

{
  "DepartmentId" : 50,
  "DepartmentName" : "Shipping",
  "Employee" : {
    "items" : [ {
       "EmployeeId" : 120,
       "FirstName" : "Matthew",
       "LastName" : "Weiss",
       "Email" : "MWEISS",
       "JobId" : "ST_MAN",
       "DepartmentId" : 50,
       "Salary" : 8000,
       "links" : [ {
         "rel" : "self",
         "href" : "<base_url>/Department/50/child/Employee/120",
         "name" : "Employee",
         "kind" : "item"
       }, {
         "rel" : "parent",
         "href" : "<base_url>/Department/50",
         "name" : "Department",
         "kind" : "item"
       } ]
     }, {
       "EmployeeId" : 121,
       "FirstName" : "Adam",
       "LastName" : "Fripp",
       "Email" : "AFRIPP",
       "JobId" : "ST_MAN",
       "DepartmentId" : 50,
       "Salary" : 8200,
       "links" : [ {
         "rel" : "self",
         "href" : "<base_url>/Department/50/child/Employee/121",
         "name" : "Employee",
         "kind" : "item"
       }, {
         "rel" : "parent",
         "href" : "<base_url>/Department/50",
         "name" : "Department",
         "kind" : "item"
       } ]
     }, {
       ...
       } ]
     } ],
     "count" : 3,
     "hasMore" : false,
     "limit" : 25,
     "offset" : 0,
     "links" : [ {
         "rel" : "self",
         "href" : "<base_url>/Department/50/child/Employee",
         "name" : "Employee",
         "kind" : "collection"
     } ]
   },     
   "links" : [ {
       "rel" : "self",
       "href" : "<base_url>/Department/50",
       "name" : "Department",
       "kind" : "item"
    } ]
}

REST API Framework Version 1 or Version 2

Version 1 and version 2 of the REST API framework return the nested child resource expanded in the response payload as an array of resource items. If the resource collection being fetched is large, you may have to make several requests since the array of resource items has a limit.

The following samples illustrate functionality for REST API framework version 1 and version 2.

The first request sample (URL 1) retrieves a single child resource item identified by employee 120. The URL parameter child identifies the relationship of the requested resource Employee.

The second request (URL 2) shows the use of the query parameter expand to ensure that all nested Employee resource items will be returned with Department resource collection 50.

The third request (URL 3) shows the use of accessor dot notation (for example, Employee.JobHistory) in combination with the query parameter expand to ensure that all nested JobHistory resource items will be returned with the Employee resource items for the Department resource collection 80.

Request Made With Framework Version 1 or Version 2

URL 1

<base_url>/Department/50/child/Employee/120
URL 2

<base_url>/Department/50?expand=Employee
URL 3

<base_url>/Department/80?expand=Employee.JobHistory&onlyData=true
HTTP Method

GET
Query Parameter

expand

When this parameter is provided in combination with REST API framework version 1, the specified children are included as links in the resource payload. The value of this query parameter is all or <accessor1>,<accessor2>,... More than one child can be specified using comma as a separator. Example: ?expand=Employee,Localization. Nested children can also be provided following the format "Child.NestedChild" (Example: ?expand=Employee.Manager). If a nested child is provided (Example: Employee.Manager), the missing children will be processed implicitly. For example, ?expand=Employee.Manager is the same as ?expand=Employee,Employee.Manager (which will expand Employee and Manager).
Content-Type

none
Payload

none

Response From Framework Version 1 or Version 2

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload 1

{
  "EmployeeId" : 120,
  "FirstName" : "Matthew",
  "LastName" : "Weiss",
  "Email" : "MWEISS",
  "JobId" : "ST_MAN",
  "DepartmentId" : 50,
  "Salary" : 8000,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department/50/child/Employee/120",
    "name" : "Employee",
    "kind" : "item"
  }, {
    "rel" : "parent",
    "href" : "<base_url>/Department/50",
    "name" : "Department",
    "kind" : "item"
  } ]
}

Payload 2

{
  "DepartmentId" : 50,
  "DepartmentName" : "Shipping",
  "Employee" : [ {
    "EmployeeId" : 120,
    "FirstName" : "Matthew",
    "LastName" : "Weiss",
    "Email" : "MWEISS",
    "JobId" : "ST_MAN",
    "DepartmentId" : 50,
    "Salary" : 8000,
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/50/child/Employee/120",
      "name" : "Employee",
      "kind" : "item"
    }, {
      "rel" : "parent",
      "href" : "<base_url>/Department/50",
      "name" : "Department",
      "kind" : "item"
    } ]
  }, {
    "EmployeeId" : 121,
    "FirstName" : "Adam",
    "LastName" : "Fripp",
    "Email" : "AFRIPP",
    "JobId" : "ST_MAN",
    "DepartmentId" : 50,
    "Salary" : 8200,
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/50/child/Employee/121",
      "name" : "Employee",
      "kind" : "item"
    }, {
      "rel" : "parent",
      "href" : "<base_url>/Department/50",
      "name" : "Department",
      "kind" : "item"
    } ]
  }, {
     ...
    } ]
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department/50",
    "name" : "Department",
    "kind" : "item"
  } ]
}

Payload 3

{
    "DepartmentId" : 80,
    "DepartmentName" : "Sales",
    "RelState" : null,
    "Employee" : [
        ...
        {
            "EmployeeId" : 176,
            "FirstName" : "Jonathon",
            "LastName" : "Taylor",
            "Email" : "JTAYLOR",
            "JobId" : "SA_REP",
            "DepartmentId" : 80,
            "Salary" : 8600,
            "CommissionPct" : 0.2,
            "JobHistory" : [
                {
                    "EmployeeId" : 176,
                    "StartDate" : "2011-03-24",
                    "EndDate" : "2012-12-31",
                    "JobId" : "SA_REP",
                    "DepartmentId" : 80
                },
                {
                    "EmployeeId" : 176,
                    "StartDate" : "2013-01-01",
                    "EndDate" : "2015-03-31",
                    "JobId" : "SA_MAN",
                    "DepartmentId" : 80
                }
            ]
        },
       ...
    ]
}

Fetching Data Only for a Business Object

REST APIs support retrieving only the data of a resource collection.

The following sample fetches the values of the Employee resource collection attributes. The query parameter onlyData ensures the resource is filtered to contain only data in the response payload and no links.

Request

URL

<base_url>/Employee?onlyData=true
HTTP Method

GET
Query Parameter

onlyData

This parameter filters the resource item payload to contain only data (no links section, for example).
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload

{
  "items" : [ {
    "EmployeeId" : 101,
    "FirstName" : "Neena",
    "LastName" : "Smith",
    "Email" : "NSMITH",
    "JobId" : "AD_VP",
    "DepartmentId" : 90,
    "Salary" : 2000
  }, {
    "EmployeeId" : 102,
    "FirstName" : "Lex",
    "LastName" : "De Haan",
    "Email" : "LDEHAAN",
    "JobId" : "AD_VP",
    "DepartmentId" : 90,
    "Salary" : 3000
  }, {
    "EmployeeId" : 103,
    "FirstName" : "Alexander",
    "LastName" : "Hunold",
    "Email" : "AHUNOLD",
    "JobId" : "IT_PROG",
    "DepartmentId" : 60,
    "Salary" : 4000
  }, {
    "EmployeeId" : 104,
    "FirstName" : "Bruce",
    "LastName" : "Ernst",
    "Email" : "BERNST",
    "JobId" : "IT_PROG",
    "DepartmentId" : 60,
    "Salary" : 5000
  }, {
    "EmployeeId" : 105,
    "FirstName" : "David",
    "LastName" : "Austin",
    "Email" : "DAUSTIN",
    "JobId" : "IT_PROG",
    "DepartmentId" : 60,
    "Salary" : 6000
  } ],
  "count" : 5,
  "hasMore" : true,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Employee",
    "name" : "Employee",
    "kind" : "collection"
  } ]
}

Filtering a Business Object with a Query Parameter

REST APIs support fetching a resource collection using query expression syntax to filter resource items.

The resource collection may be queried using expressions that differ in syntax depending on the REST API framework version that has been registered for the web application. For details about the REST API framework versions, see Understanding REST API Framework Version Support.

The following samples are based on two different versions of the Department resource. The URL sample showing resource 1.0 reflects the query-by-example query parameter syntax supported only by version 1 of the REST API framework. While the URL sample showing resource 2.0, reflects the rowmatch query parameter syntax supported in REST API framework version 2 (and later). In both framework scenarios, the samples fetch a filtered set of resource items of the Department resource.

Note:

For a REST API request, reserved characters that appear in a query parameter value should be encoded. For example, the + character in a timestamp value must be encoded as %2B. Additionally, resource and resource items names used in query parameter operations are case sensitive.

REST API Framework Version 2 (and later)

Starting with version 2 of the REST API framework, web applications may use an advanced query syntax, also known as rowmatch expressions, to fetch resources. For a complete description of the query syntax available in version 2 (and later), Understanding Framework Support for Query Syntax.

The following sample fetches all departments with at least one employee whose salary is equal to 10000. This is an example of fetching a parent resource collection (Department) and filtering it by a child resource collection attribute (Employee.Salary).

Request Example 1 Made With Framework Version 2

URL

<base_url>/Department?q=Employee.Salary = 10000
HTTP Method

GET
Query Parameter

q

This parameter filters the resource collection based on one or more attribute value expressions. Starting with REST API framework version 2, complex filters may combine expressions using the and and or conjunctions with matching sets of parentheses for grouping. For example, ?q=(Deptno>=10 and <= 30) and (Loc!=NY).
Content-Type

none
Payload

none

Response Example 1 From Framework Version 2

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourcecollection+json

Payload

{
  "items" : [ {
    "DepartmentId" : 70,
    "DepartmentName" : "Public Relations",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/70",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/70/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 80,
    "DepartmentName" : "Sales",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/820",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/80/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  } ],
  "count" : 2,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department",
    "kind" : "collection"
  } ]
}

The following sample fetches all departments with the numeric ID of 10 or a department name that begins with the letter "H".

Request Example 2 Made With Framework Version 2

URL

<base_url>/Department?q=DepartmentId = 10 or DepartmentName like 'H*'
HTTP Method

GET
Query Parameter

q

This parameter filters the resource collection based on one or more attribute value expressions. Starting with REST API framework version 2, complex filters may combine expressions using the and and or conjunctions with matching sets of parentheses for grouping. For example, ?q=(Deptno>=10 and <= 30) and (Loc!=NY).
Content-Type

none
Payload

none

Response Example 2 From Framework Version 2

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourcecollection+json

Payload

{
  "items" : [ {
    "DepartmentId" : 10,
    "DepartmentName" : "Administration",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/10",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/10/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 40,
    "DepartmentName" : "Human Resources",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/40",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/40/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  } ],
  "count" : 2,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department",
    "kind" : "collection"
  } ]
}

REST API Framework Version 1

Version 1 of the REST API framework supports a query-by-example syntax. No application configuration changes are required to use this syntax that is supported only in versions 1. For a description of the query syntax available in version 1 of the REST API framework, see GET Method Endpoints.

Note:

In version 1 of the ADF REST framework, when you create a query with a string matching filter parameter and the string to match contains a query syntax reserved word (such as AND or OR), then the quoted string must be delimited by a space character to separate it from other parameters in the query expression. For example, the following query attempts to filter on the quoted string ‘Accounting and Finance’. Since the string contains the reserved word AND, the string matching filter parameter requires a space before and after the single quotes to be viable in version 1.

?q=DepartmentName= 'Accounting and Finance' &fields=DepartmentName,Location

Note that starting in framework version 2, the use of a space character is no longer required to delimit a string matching filter that contains a reserved word.

The following sample fetches departments assigned a DepartmentId value less than 30.

Request Made With Framework Version 1

URL

<base_url>/Department?q=DepartmentId<30
HTTP Method

GET
Query Parameter

q

This parameter filters the resource collection based on one or more attribute value expressions. In REST API framework version 1, the value of this query parameter is a list of semi-colon separated query-by-example expressions. For example, ?q=Deptno=10 and <=30;Loc!=NY.
Content-Type

none
Payload

none

Response From Framework Version 1

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourcecollection+json

Payload

{
  "items" : [ {
    "DepartmentId" : 10,
    "DepartmentName" : "Administration",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/10",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/10/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  }, {
    "DepartmentId" : 20,
    "DepartmentName" : "Marketing",
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/20",
      "name" : "Department",
      "kind" : "item"
    }, {
      "rel" : "child",
      "href" : "<base_url>/Department/20/child/Employee",
      "name" : "Employee",
      "kind" : "collection"
    } ]
  } ],
  "count" : 2,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department",
    "name" : "Department",
    "kind" : "collection"
  } ]
}

Creating Business Object Items

REST APIs support the HTTP POST method to create a resource item.

REST APIs support the following creation use cases:

Creating a resource item in an existing resource collection.
Creating a child item and parent resource item (where the resource collection of each item form a child-parent relationship) in one roundtrip.

Creating a Business Object Item

REST APIs support using the HTTP POST method to create a resource item in an existing resource collection.

The following sample creates a new resource item in the existing Department resource collection.

Request

URL

<base_url>/Department
HTTP Method

POST
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload

{
  "DepartmentId" : 15,
  "DepartmentName" : "NewDept"
}

Response

HTTP Code

201
Content-Type

application/vnd.oracle.adf.resourceitem+json
Location

<base_url>/Department/15

Payload

{
  "DepartmentId" : 15,
  "DepartmentName" : "NewDept",
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department/15",
    "name" : "Department",
    "kind" : "item"
  }, {
    "rel" : "child",
    "href" : "<base_url>/Department/15/child/Employee",
    "name" : "Employee",
    "kind" : "collection"
  } ]
}

Creating an Item of a Child Business Object

REST APIs support creating a resource item in the child resource collection of an existing parent resource collection. Alternatively, REST APIs support creating a child item and the parent item in one roundtrip. Creating a child resource item and it’s parent resource item will only succeed when both the child resource item and parent resource item do not exist.

The following samples create resource items using a POST method. The first request sample (URL1) creates a child resource item identified by employee 999 in the Employee resource collection nested in existing parent resource item 15 of the Department collection. The second request (URL2) creates a child resource item identified by employee 99999 in the Employee resource collection and also creates the parent resource item 17 of the Department collection in one roundtrip.

Request

URL 1

<base_url>/Department/15/child/Employee
URL 2

<base_url>/Department
HTTP Method

POST
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload 1

{
     "EmployeeId": 999,
     "FirstName": "New",
     "LastName": "Guy",
     "Email": "NGUY",
     "JobId": "SA_REP",
     "DepartmentId": 15,
     "Salary": 9999
}

Payload 2

{
     "DepartmentId": 17,
     "DepartmentName": "NewerDept",
     "Employee": [
         {
             "EmployeeId": 99999,
             "FirstName": "Newer",
             "LastName": "Guy",
             "Email": "NRGUY",
             "JobId": "SA_MAN",
             "DepartmentId": 17,
             "Salary": 10001
         }
     ]
}

Response

HTTP Code

201
Content-Type

application/vnd.oracle.adf.resourceitem+json
Location

<base_url>/Department/15/child/Employee/999

Payload 1

{
  "EmployeeId" : 999,
  "FirstName" : "New",
  "LastName" : "Guy",
  "Email" : "NGUY",
  "JobId" : "SA_REP",
  "DepartmentId" : 15,
  "Salary" : 9999,
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department/15/child/Employee/999",
    "name" : "Employee",
    "kind" : "item"
  }, {
    "rel" : "parent",
    "href" : "<base_url>/Department/15",
    "name" : "Department",
    "kind" : "item"
  } ]
}

Location

<base_url>/Department/17

Payload 2

{
  "DepartmentId" : 17,
  "DepartmentName" : "NewerDept",
  "Employee" : [ {
    "EmployeeId" : 99999,
    "FirstName" : "Newer",
    "LastName" : "Guy",
    "Email" : "NRGUY",
    "JobId" : "SA_MAN",
    "DepartmentId" : 17,
    "Salary" : 10001,
    "links" : [ {
      "rel" : "self",
      "href" : "<base_url>/Department/17/child/Employee/99999",
      "name" : "Employee",
      "kind" : "item"
    }, {
      "rel" : "parent",
      "href" : "<base_url>/Department/17",
      "name" : "Department",
      "kind" : "item"
    } ]
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department/17",
    "name" : "Department,
    "kind" : "item"
  } ]
}

Updating a Business Object Item

REST APIs support the HTTP PATCH method to update the resource item.

Update will only succeed when the row already exists.

The following sample updates department 15, where DepartmentName is changed in the request payload.

Request

URL

<base_url>/Department/15
HTTP Method

PATCH
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload

{
  "DepartmentId" : 15,
  "DepartmentName" : "UpdatedDeptName"
}

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload

{
  "DepartmentId" : 15,
  "DepartmentName" : "UpdatedDeptName",
  "links" : [ {
    "rel" : "self",
    "href" : "<base_url>/Department/15",
    "name" : "Department",
    "kind" : "item"
  }, {
    "rel" : "child",
    "href" : "<base_url>/Department/15/child/Employee",
    "name" : "Employee",
    "kind" : "collection"
  } ]
}

Deleting a Business Object Item

REST APIs support the HTTP DELETE method to delete a resource item.

REST APIs do not currently support deleting the resource collection.

The following sample (URL1) deletes the resource item, employee 99999 in department 17. The second request URL deletes the resource item, department 17.

Request

URL 1

<base_url>/Department/17/child/Employee/99999
URL 2

<base_url>/Department/17
HTTP Method

DELETE
Content-Type

none
Payload

none

Response

HTTP Code

204
Content-Type

none
Payload

none