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 nine REST framework versions (1 to 9). 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 client. Oracle recommends using the latest
framework version to take advantage of the latest features. You can find the framework
version information for an API in the defaultFrameworkVersion
and
allowedFrameworkVersions
properties, in the response body of a GET
request for the <context root>
of the resource endpoint. For
example,
{
"items" : [
{
"version" : "11.13.18.05",
"isLatest" : true,
"adf:extension" : {
"defaultFrameworkVersion" : "3",
"allowedFrameworkVersions" : [ "1", "2", "3", "4" ]
},
}
]
}
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 nine 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 q
query 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 expand
andfields
query parameters to return nested child items along with parent. The children in the response payload now contain additional paging information such ashasMore
field, 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,
businessPlans
resource has aPeriodTypeCode
field, and its valid values come from a separate/salesGLPeriodTypes
resource.A dependent LOV provides valid values based on another field's value. For example, valid values of
PeriodStartDisplayName
field 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 @context
is introduced with all item context information placed within it, in the response payload. This new@context
field 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@context
section.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,invoices
resource has aBusinessUnit
field. A validBusinessUnit
value comes from another resource. This row-levelBusinessUnitVVO1
LOV 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.Version 8 This version introduces the following changes: - Support for storing and retrieving data of type ClobDomain as a plain string instead of base64 encoded value.
- For requests sent to multi-select Fixed Choice List (FCL) fields, the values returned in the response are presented in an array instead of comma-separated list of values.
- If an attribute is used as an identifier attribute in the resource URL, and the attribute value contains special characters, then the attribute value is encoded to make the resource URL constructed properly.
Version 9 This version introduces the following changes: - In the response body, any numeric value with a high-precision number is
treated as JSON '
string
' data type to prevent the REST client from misinterpreting the value or even rounding it off due to the field length constraints. - If you send a GET request with query parameters on accessors that aren't enabled, you get a 404 error.
- When using the LIKE operator with the
q
query parameter, you can use the backslash(\)
escape character to represent any of the wildcard characters.
- Use the
REST-Framework-Version
custom 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=true
Example 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/invoices
Example 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/describe
Example 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/describe
Example 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/invoices
Example 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/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/invoices
Example 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://servername.fa.us2.oraclecloud.com/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/describe
Example 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/describe
Example 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/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/crmRestApi/resources/11.13.18.05/opportunities/CDRM_113480",
"name": "opportunities",
"kind": "item"
},
Example: REST Framework Version 8
Because this framework version introduces three changes, each change is presented as a bullet point, and contains its own set of examples and explanation.
- Support for ClobDomain Data Type
In framework version 7 and earlier, if you send a request involving data of type ClobDomain, it must be presented in base64 encoded format. Otherwise, the request fails. Starting from framework version 8, you can use plain text in request body for ClobDomain data type values and expect the response to return the data in plain text. In this example, you'll see how it works.
Suppose, for a products
resource, the 'Description' text is of the data type ClobDomain. Using
framework 7, when you send a create request with the ClobDomain data type value presented in
plain text ("Description" : "Marker
description"
), the response fails.
cURL Command
curl --user <username:password> -X POST -d '{"ProductId":201, "ProductCode":"MARKER", "Name": "Marker", "ProductType": 1, "Description": "Marker description"}' -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products
Example Response Body (prior framework versions)
{
"title" : "Bad Request",
"status" : "400",
"o:errorDetails" : [ {
"detail" : "Unable to parse the provided payload",
"o:errorCode" : "27521"
}
But when you send the request with the value encoded in base64
format ("Description" :
"TWFya2VyIGRlc2NyaXB0aW9u"
), the record is created.
cURL Command
curl --user <username:password> -X POST -d '{"ProductId":201, "ProductCode":"MARKER", "Name": "Marker", "ProductType": 1, "Description": "TWFya2VyIGRlc2NyaXB0aW9u"}' -H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products
Example Response Body (prior framework versions)
{
"ProductId" : 201,
"ProductCode" : "MARKER",
"Name" : "Marker",
"Description" : "TWFya2VyIGRlc2NyaXB0aW9u",
"ProductType" : "1",
"@context" : {
"key" : "201",
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/201",
"name" : "products",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/201",
"name" : "products",
"kind" : "item"
} ]
}
}
When you use framework version 8, you can send the request with
the value in plain text ("Description" : "Marker
description"
) instead of encoding it. You can see that on successful creation of
the record, the response returns the value in plain text.
cURL Command
curl --user <username:password> -X POST -d '{"ProductId":201, "ProductCode":"MARKER", "Name": "Marker", "ProductType": 1, "Description": "Marker description"}' -H 'REST-Framework-Version:8' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products
Example Response Body (version 8)
{
"ProductId" : 201,
"ProductCode" : "MARKER",
"Name" : "Marker",
"Description" : "Marker description",
"ProductType" : "1",
"@context" : {
"key" : "201",
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/201",
"name" : "products",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/201",
"name" : "products",
"kind" : "item"
} ]
}
}
- Multi-Choice Lists Appear in an Array
Starting framework version 8, if requests contain multi-choice list of values, they must be presented in an array instead of comma-separated values. Otherwise, the request fails.
In this example, let's look at a request that aims at creating a
record for the products
resource, with list of
values 1 and 2 presented in an array ("ProductType": ["1",
"2"]
). Framework version 7 and earlier support creating list of values when
presented only in the comma-separated values format. Therefore, a request to create the
values as an array fails because the framework is unable to parse the values as an
array.
cURL Command
curl --user <username:password> -X POST -d '{"ProductId":302, "ProductCode":"MARKER", "Name": "Marker", "ProductType": ["1", "2"]}'-H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products
Example Response Body (prior framework versions)
{
"title" : "Bad Request",
"status" : "400",
"o:errorDetails" : [ {
"detail" : "Unable to parse the provided payload value for ProductType: Array value not expected.",
"o:errorCode" : "27535"
}
If the same request is sent with values presented in
comma-separated values format ("ProductType":
"1,2"
), the record is successfully created.
cURL Command
curl --user <username:password> -X POST -d '{"ProductId":302, "ProductCode":"MARKER", "Name": "Marker", "ProductType": "1,2"}'-H 'REST-Framework-Version:7' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products
Example Response Body (prior framework versions)
{
"ProductId" : 302,
"ProductCode" : "MARKER",
"Name" : "Marker",
"Description" : null,
"ProductType" : "1,2",
"Picture" : null,
"@context" : {
"key" : "302",
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/302",
"name" : "products",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/302",
"name" : "products",
"kind" : "item"
} ]
}
}
But in framework version 8, the record is successfully created when the list of values are presented in an array.
cURL Command
curl --user <username:password> -X POST -d '{"ProductId":302, "ProductCode":"MARKER", "Name": "Marker", "ProductType": ["1", "2"]}'-H 'REST-Framework-Version:8' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products
Example Response Body (version 8)
{
"ProductId" : 302,
"ProductCode" : "MARKER",
"Name" : "Marker",
"Description" : null,
"ProductType" : [ 1, 2 ],
"Picture" : null,
"@context" : {
"key" : "302",
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/302",
"name" : "products",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/products/302",
"name" : "products",
"kind" : "item"
} ]
}
}
Note:
On the contrary, comma-separated values aren't supported in framework version 8. So, if you are using framework version 8, don't send the requests for creating list of values in the comma-separated values format. If you do so, the request fails and you get the following response:{
"title" : "Bad Request",
"status" : "400",
"o:errorDetails" : [ {
"detail" : "Unable to parse the provided payload value for ProductType: Array value expected.",
"o:errorCode" : "27534"
}
- Handling of Special Characters in Key Attributes
In framework version 7 and earlier, if the primary key or row
finder key contains data that has special characters, such as a date value with forward
slash (/) as the separator, the REST resource links returned in response are not correct.
Starting from framework version 8, this issue is fixed and correct resource URL links are
returned in the response. In this example, let's look at a resource that contains a forward
slash in its key value. First, let's retrieve details for the record "CatId" : 2
from the cats
resource.
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" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats?q=CatId=2
Example Response Body (prior framework versions)
{
"items" : [ {
"CatId" : 2,
"CatCode" : "ELEC/COMPUTER",
"@context" : {
"key" : "ELEC/COMPUTER",
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%2FCOMPUTER",
"name" : "cats",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%2FCOMPUTER",
"name" : "cats",
"kind" : "item"
} ]
}
} ],
"count" : 1,
"hasMore" : false,
"limit" : 25,
"offset" : 0,
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/resources/<version>/cats",
"name" : "cats",
"kind" : "collection"
} ]
}
In the response, you would notice that "key" : "ELEC/COMPUTER"
contains a forward slash.
Although the forward slash (/) is encoded to %2F
as per the percent encoding rule applied to reserved characters, it's not fit to be used in
a URL. Owing to the URL encoding standards, the percent symbol in the URL needs to again
undergo percent-encoding (%
changes to %25
) to make it fit for use in a URL. As a result, the
path parameter for the key changes from ELEC%2FCOMPUTER
to ELEC%252FCOMPUTER
.
In framework version 7 and earlier, if you try to retrieve the details using this path
parameter in the URL, it doesn't work.
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" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER
The request fails with error:
HTTP/1.1 404 Not Found
But framework version 8 supports this encoding. Therefore, when you send a request to retrieve the details, the URL returned in the response is set as per the encoding standards.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:8' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats?q=CatId=2
Example Response Body (version 8)
{
"items" : [ {
"CatId" : 2,
"CatCode" : "ELEC/COMPUTER",
"@context" : {
"key" : "ELEC%2FCOMPUTER",
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER",
"name" : "cats",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER",
"name" : "cats",
"kind" : "item"
} ]
}
} ],
"count" : 1,
"hasMore" : false,
"limit" : 25,
"offset" : 0,
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/resources/<version>/cats",
"name" : "cats",
"kind" : "collection"
} ]
}
And when you use the encoded path parameter value (ELEC%252FCOMPUTER
) in the URL, you can expect a valid
response.
cURL Command
curl --user <username:password> -H 'REST-Framework-Version:8' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER
Example Response Body (version 8)
{
"CatId" : 2,
"CatCode" : "ELEC/COMPUTER",
"@context" : {
"key" : "ELEC%2FCOMPUTER",
"links" : [ {
"rel" : "self",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER",
"name" : "cats",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://servername.fa.us2.oraclecloud.com/<apiname>/resources/<version>/cats/ELEC%252FCOMPUTER",
"name" : "cats",
"kind" : "item"
} ]
}
}
Example: REST Framework Version 9
Because this framework version introduces three changes, each change is presented as a bullet point and contains its own set of examples and explanation.
- Support for High-precision Numeric Values
If you are retrieving a value that's more than 15 digits, the value might be truncated or rounded off due to precision requirements. To prevent loss of data, high-precision numeric values are converted to JSON string type. The REST client would be able to process such values in the describe and response payload as strings.
Example Response Body (prior framework versions)
The format of the returned numeric value is of type 'int64
'.
{
"EmpId": {
"type": "integer",
"format": "int64",
"nullable": false,
"x-hints": {
"precision": 18
}
}
}
Example Response Body (version 9)
The format of the returned numeric values is of type 'BigInt
'
{
"EmpId": {
"type": "string",
"format": "BigInt",
"maxLength" : 18,
"nullable": false,
"x-hints": {
"operators": ["=", ">", ">=", "<", "<=", "<>"]
}
}
}
- Error When Using Query Parameters with Invalid Accessors
For a GET request to be successful, you must use the permitted query parameters along with
the accessors that are enabled for the REST service. Before framework version 9, if you used
query parameters on accessors that aren't enabled, you wouldn't get any error. Starting
framework version 9, if you're using any of the query parameters such as
?fields
, ?expand
, ?partialDescription
,
?polymorphicType
, ?partialDescriptionForCatalog
on
accessors that aren't enabled, the REST client presents a 400 Bad request
error.
- Support for Wildcard Characters in q Query
Starting framework version 9, ?q
queries that involve a LIKE operator, may
use a \
(backslash) character as an escape character to support queries for
wildcard characters such as %
(percent), *
(asterisk),
_
(underscore),?
(question mark), and \
(backslash). For example:
?q=DeptName like '%\%%' - query for DeptName containing %
?q=DeptName like '%\*%' - query for DeptName containing *
?q=DeptName like '%\_%' - query for DeptName containing _
?q=DeptName like '%\?%' - query for DeptName containing ?
?q=DeptName like '%\\%' - query for DeptName containing \