Set the REST Framework Version
Oracle Applications Cloud REST APIs internally utilize a REST API framework to ease the development experience. This framework supports interacting with REST resources based on ADF Business Components. All REST APIs using this framework support a custom HTTP header, REST-Framework-Version, which allows a REST client to control the REST API behavior.
Choose a REST Framework Version
For your application development, you can choose any one version among the seven REST framework versions (1 to 7). The version you choose for your client depends on your business needs.
Default Framework Version
Oracle Applications Cloud REST APIs use framework version 1 by default. If it's appropriate for your business needs, then you're all set. If not, you can specify a different framework version in your API client. Oracle recommends using the latest framework version to take advantage of the latest features.
Note:
The changes introduced in each framework version are backward incompatible. Therefore, assess your business requirements and use the framework version that supports them.To set the REST framework version for a client request:
-
Choose one of the seven supported framework versions:
Framework Description Version 1 The base framework version that's used to process client requests. Version 2 Supports expanded query expression syntax for client requests. Version 2 interprets the qquery parameter differently.Version 3 Supports retrieving nested child resources for client requests as a resource collection (JSON object), instead of an array of items. Use the GET method against parent resource with expandandfieldsquery parameters to return nested child items along with parent. The children in the response payload now contain additional paging information such ashasMorefield, which can be used to determine whether additional child items can be retrieved in subsequent requests.Version 4 Prior to version 4, the response payload only contains the error message as a string if a REST request fails. In version 4 and above, the error response payload contains richer information such as application-specific error code, error path that pinpoints where the error occurs, and details if an error is caused by other errors. Version 5 This version introduces two changes: - For custom methods returning non-string values, the response payload displays the value in the actual data type instead of displaying it as a string.
- If a field is a dependent List of Value (LOV) field, then you may see that its LOV resource URL changes from a sub-resource to a root resource. LOV provides the list of valid values for a field. For example,
businessPlansresource has aPeriodTypeCodefield, and its valid values come from a separate/salesGLPeriodTypesREST resource.A dependent LOV provides valid values based on another field's value. For example, valid values of
PeriodStartDisplayNamefield depends on value ofPeriodTypeCode.Prior to version 5, all dependent LOV resources are sub-resources, such as
/salesGLPeriodTypes/{PeriodTypeCode}/child/salesGLStartPeriodTimes. In version 5, some dependent LOV resources become root resources such as/salesGLStartPeriodTimesLOV. But client can still filter the dependent LOV resource based on its dependent field value, such as using a finder query parameter?finder=StartPeriodFinder;bindPeriodType={PeriodTypeCode}.
Version 6 A new field @contextis introduced with all item context information placed within it, in the response payload. This new@contextfield is a sibling of any regular field. It's of JSON object type and includes key, headers, links, and warnings if there are any.Note:
Links are available even in prior versions, but in version 6, they are moved into the@contextsection.Version 7 Hides the row-level LOVs. Only the root-level LOV resource links are displayed in the resource metadata and resource data. A row-level LOV resource is a sub-resource with its URL containing
lov, such as/invoices/180428/lov/BusinessUnitVVO1. In this example,invoicesresource has aBusinessUnitfield. A validBusinessUnitvalue comes from another resource. This row-levelBusinessUnitVVO1LOV resource is always a sub-resource of an existing invoice resource, such as invoice180428. Therefore, a row-level LOV isn't useful when choosing a value, while creating a new invoice. Instead, client should use a root-level LOV resource so that both create and update operations are covered. - Use the
REST-Framework-Versioncustom HTTP header in the client request to specify the framework version. For example, if you want to use framework version 3, include the header-H 'REST-Framework-Version:3'in the request.
To learn more about the framework versions, see:
- Working with ADF REST Framework Versions
- What Happens At Runtime: Invoking an ADF REST Framework Version
Note:
The REST framework versions are not applicable to SCIM and BPM resources.Examples
Let's look at some examples of how the REST API behavior changes, depending on the framework version selected for processing the request.
Example: REST Framework Versions 1 and 2
In REST framework version 1, the query parameter is limited to the query-by-example syntax, with limited operators supported, and without filtering based on child. For example: q=deptno>=10 and <= 30;loc!=NY. In REST framework version 2 and later, advanced query syntax is supported: more operators, filtering based on child resource fields, and UPPER function. For example, q=Deptno > 5 and (Emps.Job = 'MANAGER' or Emps.DirectReports.Sal >= 2000).
Let's look at this example based on framework version 2. The request uses a filter with multiple expressions to retrieve a specific record from the accounts resource.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:2' https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/accounts?q=OwnerName like 'Toddar%' and PartyNumber='CDRM_448' and PartyId='100100001740800'Example Response Body
{
"items": [
{
"PartyId": 100100001740800,
"PartyNumber": "CDRM_448",
"SourceSystem": "RNOW",
"SourceSystemReferenceValue": "291",
"OrganizationProfileId": 100100001740800,
"OrganizationName": "146201273770710561",
"UniqueNameSuffix": "(San Mateo, US)",
"PartyUniqueName": "146201273770710561 (San Mateo, US)",
"Type": "ZCA_CUSTOMER",
"SalesProfileNumber": "TEMPORARY2293488",
"OwnerPartyId": 100010037920358,
"OwnerPartyNumber": "100010037920358",
"OwnerEmailAddress": "sendmail-test-discard@oraclecloud.com",
"OwnerName": "ToddAR BeelerAR",
"PrimaryContactPartyId": null,
"PrimaryContactPartyNumber": null,
"PrimaryContactSourceSystem": null,
"PrimaryContactSourceSystemReferenceValue": null,
"PrimaryContactName": null,
"PrimaryContactEmail": null,
"PrimaryContactPhone": null,
...
}
]
}Example: REST Framework Version 3
In this example, you can see that a nested child collection resource is retrieved along its parent and represented as a JSON object, instead of an array. Using the InvoiceId field, you can retrieve the invoiceLines child resources as a resource collection.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:3' https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices?fields=InvoiceId;invoiceLines:Description,ShipToLocation,Requester&onlyData=trueExample Response Body
{
"items": [
{
"InvoiceId": 353933,
"invoiceLines": {
"items": [
{
"Description": "Foreign currency Standard unmatched Invoice with lines, distributions and installments",
"ShipToLocation": M1-_SEATTLE_MFG_0_2450399171831,
"Requester": Adams,Joshua
}
],
"count": 1,
"hasMore": false,
"limit": 25,
"offset": 0,
"links": [
{
"rel": "self",
"href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices/353933/child/invoiceLines",
"name": "invoiceLines",
"kind": "collection"
}
]
}
},
{
"InvoiceId": 300100169282057,
"invoiceLines": {
"items": [
. . .
],
"count": 3,
"hasMore": false,
"limit": 25,
"offset": 0,
"links": [
. . .
]
}
},
. . .
],
"count": 25,
"hasMore": true,
"limit": 25,
"offset": 0,
"links": [
{
"rel": "self",
"href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.5/invoices",
"name": "invoices",
"kind": "collection"
},
. . .
]
}Example: REST Framework Version 4
In this example request to create an invoice, the InvoiceNumber field causes a validation error. The response payload contains details of the exception as a JSON object.
cURL Command
curl --user <username:password> -X POST -H 'REST-Framework-Version:4' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoicesExample Request Body
{
"InvoiceNumber": "REST Unmatched Invoice",
"InvoiceCurrency": "USD",
"InvoiceAmount": 2212.75,
"InvoiceDate": "2018-10-01",
"BusinessUnit": "Vision Operations",
"Supplier": "Advanced Network Devices",
"SupplierSite": "FRESNO",
"Requester": "Johnson,Mary",
"InvoiceGroup": "01Oct2018-Group",
"Description": "Office Supplies"
}Example Response Body
{
"title": "Bad Request",
"status": "400",
"o:errorDetails": [
{
"detail": "This invoice number already exists. Provide a unique invoice number. (AP-810776)",
"o:errorCode": "AP:::AP_RS_INV_NUM_DUPLICATE_VALUE",
"o:errorPath": "/InvoiceNumber"
}
]
}Example: REST Framework Version 5
When this framework is in use, a dependent list of value (LOV) resource may become a root-level resource instead of a nested sub-resource.
To understand the difference, let's look at this request sent to the businessPlans resource, which has a PeriodStartDisplayName field with its valid values depending on PeriodTypeCode field. This request uses framework version 4.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:4' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/businessPlans/describeExample Response Body
{
"name" : "PeriodStartDisplayName",
"type" : "string",
......
"lov" : {
"childRef" : "SalesGLStartPeriodPickerTimeListViewAccessor",
"attributeMap" : [ {
"source" : "PeriodName",
"target" : "PeriodStartDisplayName"
}, {
"source" : "Periodtype",
"target" : "PeriodTypeCode",
"derived" : true
} ],
"displayAttributes" : [ "PeriodName" ],
"lovResourcePath" : [ {
"resource" : "salesGLPeriodTypes"
}, {
"resource" : "salesGLStartPeriodTimes"
} ]
},
......
{
"rel" : "lov",
"href" : "https:// servername.fa.us2.oraclecloud.com /crmRestApi/resources/11.13.18.05/salesGLPeriodTypes",
"name" : "salesGLPeriodTypes",
"kind" : "collection"
}
}The response indicates that PeriodStartDisplayName is an LOV attribute, and its valid values come from a nested child LOV resource salesGLStartPeriodTimes, with its parent being salesGLPeriodTypes. You can retrieve the valid values of PeriodStartDisplayName using the following URL: https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/salesGLPeriodTypes/{PeriodTypeCode}/child/salesGLStartPeriodTimes, with PeriodTypeCode token replaced with the chosen PeriodTypeCode value.
However, in framework version 5, salesGLPeriodTypes LOV resource is no longer a sub-resource.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:5' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/businessPlans/describeExample Response Body
{
"name" : "PeriodStartDisplayName",
"type" : "string",
......
"lov" : {
"childRef" : "SalesGLStartPeriodPickerTimeListViewAccessor",
"childRefForCreate" : "SalesGLStartPeriodPickerTimeListViewAccessorForCreate",
"attributeMap" : [ {
"source" : "PeriodName",
"target" : "PeriodStartDisplayName"
}, {
"source" : "Periodtype",
"target" : "PeriodTypeCode",
"derived" : true
} ],
"displayAttributes" : [ "PeriodName" ]
},
......
{
"rel" : "lov",
"href" : "https:// servername.fa.us2.oraclecloud.com /crmRestApi/resources/11.13.18.05/salesGLStartPeriodTimesLOV?finder=StartPeriodFinder%3BbindPeriodType%3D{PeriodTypeCode}",
"name" : "SalesGLStartPeriodPickerTimeListViewAccessorForCreate",
"kind" : "collection"
}
}Instead, within the lov description of the attribute, the childRefForCreate property identifies the LOV resource. You can observe that the href of that LOV contains a root-level resource URL:
https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/salesGLStartPeriodTimesLOV?finder=StartPeriodFinder;bindPeriodType={PeriodTypeCode}To retrieve valid PeriodStartDisplayName values, you need to use the GET request on the given URL, replacing the PeriodTypeCode token with the chosen PeriodTypeCode value.
Note:
If you had defined any custom cascading Fixed Choice List (FCL) on the resource and you requested for a child FCL URL, you may notice an extra filter appearing in the response. This is observed if the FCLs were created in older releases and you are using framework version 5. There's however no impact on functionality and you may ignore the filter.Example: REST Framework Version 6
In this example, you'll see how the item context information, such as links and headers, are positioned within the newly created @context element. Until framework version 5, links were placed at the same level as the resource fields.
The change indicator that was earlier placed under the self link's properties element is now moved to a new element under the header, called Etag. The ETag header value is available in the @context section for each item resource.
The @context section may also contain warnings that don't fail REST request but might be worthwhile for clients to take further action.
The first example shows where links appear when framework version 5 is in use.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:5' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoicesExample Response Body
{
"items": [
{
"InvoiceId": 180511,
"InvoiceNumber": "IBY_Group2_I2470",
"InvoiceCurrency": "SGD",
"PaymentCurrency": "SGD",
"InvoiceAmount": 63750,
"InvoiceDate": "2013-08-16",
"BusinessUnit": "Vision Operations",
"Supplier": "IBY_Supplier2",
"SupplierNumber": "1357714951",
...
"links": [
{
"rel": "self",
"href": "https://servername.fa.us2.oraclecloud.com:443/fscmRestApi/resources/11.13.18.05/invoices/180511",
"name": "invoices",
"kind": "item",
"properties": {
"changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000478"
}
}
]
}
]
}When the same request is sent using framework version 6, the response displays links appearing within the newly introduced @context section.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:6' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoicesExample Response Body
{
"items": [
{
"InvoiceId": 180511,
"InvoiceNumber": "IBY_Group2_I2470",
"InvoiceCurrency": "SGD",
"PaymentCurrency": "SGD",
"InvoiceAmount": 63750,
"InvoiceDate": "2013-08-16",
"BusinessUnit": "Vision Operations",
"Supplier": "IBY_Supplier2",
"SupplierNumber": "1357714951",
...
"LastUpdateLogin": "E4127E5109082CC8E0435360F00AF4AD",
"@context": {
"key": "180511",
"headers": {
"ETag": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000478"
},
"links": [
{
"rel": "self",
"href": "https://servernamne.fa.us2.oraclecloud.com:443/fscmRestApi/resources/11.13.18.05/invoices/180511",
"name": "invoices",
"kind": "item"},
...
} ]
}
]
}Example: REST Framework Version 7
Starting framework version 7, neither resource metadata nor resource data includes the row-level LOV. The following examples show how the response changes when the framework version changes.
The first response is from framework version 6 that displays the row-level LOV. The second response is from framework version 7, where the row-level LOV no longer appears.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:6' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describeExample Response Body (prior framework versions)
{
"name" : "BudgetedFlag",
"type" : "boolean",
......
"lov" : {
"childRef" : "YesNoLOV",
"childRefForCreate" : "YesNoLOVForCreate",
"attributeMap" : [ {
"source" : "LookupCode",
"target" : "BudgetedFlag"
} ],
"displayAttributes" : [ "Meaning" ]
}
...
{
"item" : {
"links" : [ {
"rel" : "lov",
"href" : "https:// servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/{id}/lov/YesNoLOV",
"name" : "YesNoLOV",
"kind" : "collection"
}, {
"rel" : "lov",
"href" : "https:// servername.fa.us2.oraclecloud.com /crmRestApi/resources/11.13.18.05/fndStaticLookups?finder=LookupTypeFinder%3BBindLookupType%3DYES_NO",
"name" : "YesNoLOVForCreate",
"kind" : "collection"
}
}cURL Command
curl --user <username:password> -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describeExample Response Body (version 7)
{
"name" : "BudgetedFlag",
"type" : "boolean",
......
"lov" : {
"childRef" : "YesNoLOV",
"attributeMap" : [ {
"source" : "LookupCode",
"target" : "BudgetedFlag"
} ],
"displayAttributes" : [ "Meaning" ]
},
...
{
"rel" : "lov",
"href" : "https:// servername.fa.us2.oraclecloud.com /crmRestApi/resources/11.13.18.05/fndStaticLookups?finder=LookupTypeFinder%3BBindLookupType%3DYES_NO",
"name" : "YesNoLOV",
"kind" : "collection"
}
}Observe that the following row-level LOV doesn't appear in the response body.
{
"rel" : "lov",
"href" : "https:// servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/{id}/lov/YesNoLOV",
"name" : "YesNoLOV",
"kind" : "collection"
}Similarly, the response to a request against resource data doesn't include the row-level LOV links. You can observe it in the following examples.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:6' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480/Example Response Body (prior framework versions)
{
...
"Name": "TestOpportunity",
"OptyId": 300100200556345,
"OptyNumber": "CDRM_113480",
"OwnerResourcePartyId": 100010025532672,
"PrimaryCompetitorId": 100000012079032,
...
"@context": {
"key": "CDRM_113480",
"headers": {
"ETag": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000002770400000002737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B0200007870000000067372001B6F7261636C652E6A626F2E646F6D61696E2E4E756C6C56616C75655899C1C58DAABEEB02000149000A6D53514C54797065496478700000000C78"
},
"links": [
....
{
"rel": "lov",
"href": "https://servername.fa.us2.oraclecloud.com:443/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480/lov/RatedCurrenciesVO",
"name": "RatedCurrenciesVO",
"kind": "collection"
},
}
]
}cURL Command
curl --user <username:password> -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480/Example Response Body (version 7)
The response body doesn't contain any reference to RatedCurrenciesVO LOV.
{
...
"@context": {
"key": "CDRM_113480",
"headers": {
"ETag": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000002770400000002737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B0200007870000000067372001B6F7261636C652E6A626F2E646F6D61696E2E4E756C6C56616C75655899C1C58DAABEEB02000149000A6D53514C54797065496478700000000C78"
},
"links": [
{
"rel": "self",
"href": "https://servername.fa.us2.oraclecloud.com:443/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480",
"name": "opportunities",
"kind": "item"
},