G Endpoints
REST APIs support a variety of business object tasks that you can perform using standard HTTP methods in combination with an endpoint that provides details about the resource that you want to return.
This appendix contains the following sections:
GET Method Endpoints
REST APIs support the following operations using a GET method with the URI as shown.
-
Describe the resource collection, resource item, or resource catalog (when collection and item are omitted).
<base_path>
/[{resourceCollectionPath
}|{resourceItemPath
}]/describe -
Retrieve the resource collection, optionally using a query string parameter.
<base_path>
/{resourceCollectionPath
}[?{queryStringParam
}[&{queryStringParam
}]] -
Retrieve the resource item, optionally using a query string parameter.
<base_path>
/{resourceItemPath
}[?{queryStringParam
}[&{queryStringParam
}]]
Request Parameters
-
The GET method supports query string parameters to query, filter, page, and sort the resource collection. The supported parameters are listed in the following table. All GET method URI parameters can be combined with any other parameter in the table, except where noted on the
expand
andfield
parameters. Note that query string parameters can only be used on resource media types. They cannot, for example, be used when describing the resource.
Note:
The results of the GET method or the query syntax may vary depending on the REST API framework version used for a client request. The following tables specify where the framework version is important to note when using query string parameters. For additional information about framework versions, see Working with REST API Framework Versions.
Table G-1 Supported GET Method Query String Parameters Used Only in Resource Collections
GET URI Parameter | Value | Description |
---|---|---|
Starting in REST API framework version 2, |
In framework version 1, the query parameter is used in the WHERE clause and contains one or more query by example-type expressions, separated by a semi-colon. Format: Example: Starting in framework version 2, the query parameter accepts expressions that identify the specific rows to retrieve from the resource. The filter can be as simple as a single expression, or you can create more complex filters by combining expressions using the For example, the following expression uses conjunction to query the resource using three different fields: If a query parameter value has a special character (like ‘;’, ‘,’, ‘=’ or similar), then the value (in the expression) should be enclosed in quotes to define a literal value. If the literal value contains quotes, then, in addition, the quotes need to be escaped, as defined by the framework version, to be viable:
Additionally, in version 1, if the query parameter value contains a reserved word (such as
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. For version 1, if the value contains both a special character and a reserved word, then the value needs to be enclosed in single quotes (
For a complete explanation of the expression format, see Understanding Framework Support for Query Syntax. |
The resource collection will be queried using the provided expressions. Supported operators in framework version 1 and later:
Supported operators in framework version 2 and later also include:
Allowed special characters in framework version 1:
Allowed special characters in framework version 2 and later:
For examples, see Filtering a Business Object with a Query Parameter and Understanding Framework Support for Query Syntax. Framework version 9 allows the use a |
|
boolean Default: |
The resource collection will include the estimated row count when For an example, see Returning the Estimated Count of Business Object Items. |
|
integer |
This parameter restricts the number of resource items returned inside the resource collection. If For an example, see Paging a Business Object. |
|
integer Default: 0 (the first position) |
Used to define the starting position of the resource collection. If offset exceeds the resource count, then no resources are returned. For an example, see Paging a Business Object. |
Table G-2 Supported GET Method Query String Parameters Used in Resource Collections and Resource Items
GET URI Parameter | Value | Value |
---|---|---|
Starting in REST API framework version 3 and later, |
A simple comma-separated list of resource item attributes. Format: Example: May be used on child resources. Format: < Example: May be used on nested resources using accessor dot notation. Format: < Example: Or on both resources in the nested resource. Format: < Example: |
This parameter filters the resource item attributes. Only the specified attributes are returned. Note that if a nested resource is queried using the accessor dot notation ( Note this parameter cannot be combined with the For examples, see Fetching a Business Object with a Subset of Items. |
|
boolean Default: |
This parameter filters the resource response in order to contain only data (no For an example, see Fetching Data Only for a Business Object. |
Starting in REST API framework version 3 and later, |
Display all children. Format: Display one or more child resource using a comma-separated list of accessors. Format: < Example: Display nested resources using the accessor dot notation. Format: < Example: |
When this parameter is provided, the specified children are included in the resource response (instead of the link). Note the Note that if a nested resource is queried using the accessor dot notation ( For examples, see Fetching a Child Business Object. |
|
A set of dependency attributes. Format: Example: |
The dependencies are attributes that are set before and rolled back after generating the response. The dependencies attributes are always set in the resource item in question. When a child resource collection is requested and the |
|
A comma-separated list of order-by attributes with a sort flag to specify ascending or descending order. Format: Example: Default: ORDERBY attributes defined on the business object query will be applied. |
Sorts a resource collection based on its attributes. If the By default, the fetched collection will be sorted in a case insensitive way. For an example, see Sorting a Business Object. |
|
A comma separated list of Example: |
When a resource item or a resource collection is requested and the Note the |
Table G-3 Supported GET Method Query String Parameters Used in Resource Catalog Describe
GET URI Parameter | Value | Value |
---|---|---|
|
|
Use to retrieve the resource catalog describe. The URL parameter If you do not want any metadata in the response but only self links, you can append Optionally, additional parameters may be appended to the minimal describe request, to include children resources and / or resource annotations, as explained for the query parameters For an example, see Retrieving the Resource Catalog Describe. |
|
|
Use to include all available children resources nested within a parent resource describe. You can append For a resource catalog describe example, see Retrieving the Resource Catalog Describe. |
|
|
To include resource annotations in the catalog describe, you can append Note that annotations must be defined by the web application developer and may not be present on the resource. You cannot use this parameter with |
Query String Operators Supported by REST API Data Types
The following table shows the REST API data types and the valid operators that may be used in query strings with the query (q
) parameter.
Note that the operators BETWEEN, NOT BETWEEN, IN, NOT IN, and the wildcard character % are available only starting in REST API framework version 2.
Table G-4 Operators Supported by Data Types in Query (q) String Parameter
REST API Data Type | Supported Operator |
---|---|
integer |
|
number |
|
string |
|
date |
|
time |
|
datetime Note: Both UTC and local datetime formats are supported. The value returned is determined by the time zone configured for the VM. |
|
boolean |
|
Media Types Supported
-
Request
-
None
-
-
Response
-
application/vnd.oracle.adf.resourcecollection+json
: When retrieving a resource collection. -
application/vnd.oracle.adf.resourceitem+json
: When retrieving a resource item. -
application/vnd.oracle.adf.description+json
: When describing a resource.
-
Describe Topics
Task Topics
REST API Framework Version Topics
POST Method Endpoints
REST APIs support the following tasks using a POST method with the URL as shown.
-
Create a resource item.
<base_path>
/{resourceCollectionPath
} -
Create a parent resource item and create the nested child resource collection in one roundtrip.
<base_path>
/{resourceCollectionPath
} -
Update or create a resource item resource item in an existing resource using the
Upsert-Mode
header.<base_path>
/{resourceCollectionPath
} -
Execute an a batch request.
<base_path>
/{version}
Request Parameters
-
none
Media Types Supported
-
Request
-
application/vnd.oracle.adf.resourceitem+json
: When creating a resource item. -
application/vnd.oracle.adf.resourceitem+json
: When updating or creating a resource item using Upsert. -
application/vnd.oracle.adf.batch+json
: When executing a batch request.
-
-
Response
-
application/vnd.oracle.adf.resourceitem+json
: When creating a resource item. -
application/vnd.oracle.adf.resourceitem+json
: When updating or creating a resource item using Upsert. -
application/vnd.oracle.adf.batch+json
: When executing an batch request.
-
Task Topics
PATCH Method Endpoints
REST APIs support the following operation using a PATCH method with the URL as shown.
-
Updating a resource item.
<base_path>
/{resourceItemPath
}
Request Parameters
-
none
Media Types Supported
-
Request
-
application/vnd.oracle.adf.resourceitem+json
: The resource item to be updated.
-
-
Response
-
application/vnd.oracle.adf.resourceitem+json
: The updated resource item.
-
Tasks Topics