Supported HTTP Methods

The most commonly used HTTP methods (or verbs) are GET, POST, PATCH, and DELETE. The building blocks of REST APIs, these methods define actions applied to REST resources using their URLs. See Custom Actions for more information.

Note:

REST API response time depends on several factors. Oracle recommends that you periodically review if your REST request requirements have changed. Also check with your service administrator if any capacity adjustments or other changes are required in your service configuration.
Child resources usually inherit security privileges from their parent resource. Therefore, to use a method on a child resource, you may need to have access to use that method on the parent resource. However, there may be some child resources with different privilege requirements to access them.

Note:

You can combine multiple operations into a single HTTP request to improve performance. For more information, see Batch Actions.

Method	Works with a Singular Resource?	Works with a Collection Resource?
`GET`	Yes. Gets a single resource.	Yes. Gets a subset, or all of the resources in the collection.
`POST`	No. For a custom method, you can use the `POST` method for a singular resource.	Yes. Creates a new resource in the collection.
`PATCH`	Yes. Updates a resource.	No.
`DELETE`	Yes. Deletes a resource.	No.

The GET Method

Use this method to retrieve information from a resource. To query both a singular resource and a collection resource, use expand, fields, and onlyData query parameters. To filter the queried result, use different parameters for a singular resource and a collection resource.

The list of parameters for querying singular and collection resources are:

expand

Gets the child resources along with the parent resource when you query a hierarchical resource. The server doesn't return child resources by default. The valid values include:

Name of a single child resource.
Comma-separated list of child resource names to specify multiple values.
Keyword all to expand all child resources.

Starting in REST framework version 3, the expand parameter returns the child resource items as a collection resource to support pagination of the collection. This parameter applies to both singular and collection resources.

Example URL

crmRestApi/resources/latest/opportunities/CDRM_99541?expand=OpportunityContact

Example Response Body

    "BudgetAvailableDate": null,
    "BudgetedFlag": false,
    "PrimaryOrganizationId": 5186,
    "ChampionFlag": false,
    "CreatedBy": "MHoope",
    "CreationDate": "2018-11-03T02:32:18+00:00",
    "CurrencyCode": "USD",
    "SalesMethodId": 100000012430001,
    "SalesStageId": 100000012430007,
...
 "OpportunityContact": [],
    "links": [
        {
            "rel": "self",
...
					}

fields

Gets information for the specified fields. The valid values include:

Name of a single property.
Comma-separated list of property names to specify multiple values.

Starting in REST framework version 3, the fields parameter returns the child resource items as a collection resource to support pagination of the collection. This parameter applies to both singular and collection resources.

onlyData

Indicates whether the retrieved data contains only resource field values without links. The default value is false, indicating that the retrieved data contains links by default. This parameter applies to both singular and collection resources.

Example URL

crmRestApi/resources/latest/accounts/CDRM_395053?onlyData=true

Example Response Body

{
    "PartyId": 300100089971773,
    "PartyNumber": "CDRM_395053",
    "SourceSystem": null,
    "SourceSystemReferenceValue": null,
    "OrganizationProfileId": 300100089971773,
    "OrganizationName": "BIQA_R13_AccountStanalone1",
    "UniqueNameSuffix": "(USA Fulfillment, US)",
    "PartyUniqueName": "BIQA_R13_AccountStanalone1 (USA Fulfillment, US)",
    "Type": "ZCA_PROSPECT",
    "SalesProfileNumber": "CDRM_169555",
    "OwnerPartyId": 100010037456865,
    "OwnerPartyNumber": "100010037456865",
    "OwnerEmailAddress": "sendmail-test-discard@oracle.com",
...
    "OrganizationDEO_ExtnZcmFuseEditCustomerContainerLayout_1805_CC_PageComposerHide_1529582994295Expr": "false",
    "OrganizationDEO_ExtnZcmFuseCreateCustomerLayout_1805_CC_PageComposerHide_1529582907617Expr": "false",
    "OrganizationDEO_ExtnZcmFuseCreateCustomerLayout_CC_1805_reorderFields_1529580801598Expr": "false",
    "OrganizationDEO_ExtnZcmFuseCreateCustomerLayout_CustomFormulaField_1534485112824Expr": "false",
    "OrganizationDEO_ExtnZcmFuseEditCustomerContainerLayout_CustomTextFormula_1534485211880Expr": "false",
    "OrganizationDEO_CustomText_Account_c": null,
    "OrganizationDEO_CustomDate_Account_c": null,
    "OrganizationDEO_CustomNumber_Account_c": null,
    "OrganizationDEO_CustomCurrency_Account_c": null,
    "OrganizationDEO_CustomDCL_AccountName_Id_c": null,
    "OrganizationDEO_CustomDCL_AccountName_c": null,
    "OrganizationDEO_CustomPerc_Account_c": null,
    "OrganizationDEO_WorkspaceRelation_Id_WorkspaceAccount": null
}

limit

Positive integer value that specifies the maximum number of items that a server returns. The server might override this value to improve application performance. If the client request doesn't specify a limit value, then the server uses the default limit value of 25. This parameter applies only to collection resources.

offset

Positive integer value that specifies the index of the first item to be returned. Default value is 0. This parameter applies only to collection resources. For example:

If offset=0, the response contains all the resources, starting from the first item in the collection.
If offset=10, the response contains resources starting from the 11^th item.

Specifies a filter for the items to be returned from the collection. This parameter applies only to collection resources.

In REST framework version 1, the query parameter is used in the where clause and contains one or more expressions separated by a semicolon. For example: q=deptno>=10 and <= 30;loc!=NY.

Supported operators in REST framework version 1:

= (Equal to)
> (Greater than)
< (Less than)
>= (Greater than or equal to)
<= (Less than or equal to)
!= (Not equal to)
AND (And)
OR (Or)
NOT (Not)
LIKE (Like)

The allowed special characters in REST framework version 1:

" (double quotation mark) and ' (single quotation mark) to define a literal.
\ (backslash) to define an escape character.
* (asterisk) to define a wildcard character.

For REST framework version 2 and later, the query parameter accepts a rowmatch expression format that identifies the specific rows to retrieve from the resource.

The supported operators in REST framework version 2 and later also include:

<> (Not equal to)
BETWEEN (between)
NOT BETWEEN (Not between)
IN (in)
NOT IN (Not in)
IS NULL
NOT NULL

The allowed special characters in REST framework version 2 and later:

" (double quotation mark) and ' (single quotation mark) to define a literal.
\ (backslash) to define an escape character.
% (percent) to define a wildcard character.

totalResults

Boolean value that indicates whether to include the total number of search records that match the query in the response. Default value is false. This parameter applies only to collection resources.

Example URL

crmRestApi/resources/11.13.18.05/opportunities?totalResults=true&limit=1

Example Response Body

"totalResults": 4,
"count": 1,
"hasMore": true,
"limit": 1,
"offset": 0,
"links": [
    {
        "rel": "self",
        "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities",
        "name": "opportunities",
        "kind": "collection"
    }
]

orderBy

Specifies the order of the items in the response payload. This parameter applies only to collection resources. For details, see Sorting.

finder

Uses the predefined where clause that includes certain bind parameters to search the collection. This parameter applies only to collection resources. For example, the opportunities resource defines a finder named MyOpportunitiesFinder, with one of the bind parameters named Name. A client can use this finder to fetch all opportunities named

Auto that the current user owns.

For example:

finder=MyOpportunitiesFinder;Name=Auto

In this command, the format of the query parameter value is:

<finder>;<attr1>=<val1>,<attr2>=<val2>.

dependency

Used for the list-of-values (LOV) resources. This parameter applies only to collection resources. For example, a location resource includes the following Country and State fields:


{
"Country" : "US",
"State" : "CA"
}

The location resource gets values for the State field from the States resource, which includes a list of values that depend on the Country resource. Assume you change the country to BR in the client. To display the new valid list of states, the client sends a request to the server that uses BR in the Country field and gets the associated state list.

States?dependency=Country=BR

The POST Method

Use to create a new item in a resource. The request media type is:

application/vnd.oracle.adf.resourceitem+json

Note:

You can update an existing record or create a new record in a single POST request using the Upsert-Mode header. If you set the Upsert-Mode header to true in the request and an item matches with the values specified in the request, the record is updated. Otherwise, the REST framework creates a new record. For the upsert functionality to work, ensure that the request contains the mandatory attributes of the resource required to create a resource.

The PATCH Method

Use to update data in a resource. The PATCH method updates only the fields specified in the request body. The request media type is:

application/vnd.oracle.adf.resourceitem+json

The DELETE Method

Use to delete a resource. The method doesn't require a request body. The child resources inherit the functional security of the parent resource. You must have access to delete a parent resource, in order to delete its child resource.

Custom Actions

A resource might expose a custom action that isn't the standard Create, Read, Update, and Delete (CRUD) action. For example, any custom object functions that are created on standard objects using Application Composer are available as custom actions. A custom action is always initiated using a POST method.

The relevant request media type is:

application/vnd.oracle.adf.action+json

The response media type is:

application/vnd.oracle.adf.actionresult+json

The following request always contains a custom action and optionally, an array of input parameters for the custom action:

application/vnd.oracle.adf.action+json

The JSON schema of the media type is:


{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "Action execution representation.",
    "description": "Represents the action execution and its parameters.",
    "properties": {
        "name": {
            "type": "string",
            "description": "Action name."
        },
        "parameters": {
            "type": "array",
            "description": "Parameter name/value pair.",
        }
    },
    "required": [
        "name"
    ]
}