1. REST API for Launch in Oracle Fusion Cloud CX for IndustriesREST API Reference for Launch Cloud Service
  2. Learn More
  3. Set the REST Framework Version

Set the REST Framework Version

Oracle Applications Cloud REST APIs utilize our own end-to-end ADF REST API framework, simplifying the development experience. This framework supports creating and interacting with resources and REST services based on ADF Business Components. Client application developers can then use REST APIs to easily interact with public business objects. The different versions of the REST framework provide alternative ways of controlling REST API behavior.

Choosing a REST Framework Version

You can choose among ADF REST framework versions, 1, 2, 3, or 4. The version you choose for your client depends on your business needs.

Discovering your Default Framework Version

Oracle ADF REST resources usually come with a default ADF REST runtime framework version. If this default framework is appropriate for your business needs, then you're all set. If it's not, you can override the default ADF REST runtime framework version by specifying a different ADF REST runtime framework version in your API client using the custom header, REST-Framework-Version.

To set the REST framework version for a client request:

  1. Choose one of the four supported framework versions:
    Framework Description
    Version 1 The base framework version that's used to process client requests. Note that the query-by-example resource query syntax supported in version 1 is not compatible with later versions of the ADF REST framework.
    Version 2 Supports expanded query expression syntax for client requests. Version 2 introduces a backward-incompatible change for client requests that use version 1, because version 2 interprets the q query parameter differently.
    Version 3 Supports retrieving nested child resources for client requests as a collection resource, instead of an array of items, as in versions 1 and 2. Use the GET method with expand and fields query parameters to return a nested child resource with the hasMore attribute, and determine whether you can return more resource items in subsequent requests. Version 3 introduces a backward-incompatible change for client requests that use version 1 or 2, because of the difference in the payload structure.
    Version 4 Supports responses in the form of an exception detail payload that provides benefits to the web application, including details of each error in a hierarchical structure if multiple errors occur in a single request. It Identifies the exception corresponding to each error by including an application-specific error code, and presents an error path that identifies the location of each error in the request payload structure. However, the exception detail may or may not present certain details, such as the application-specific error code or the request payload's error path.

    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 a PeriodTypeCode 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 of PeriodTypeCode.

      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 a BusinessUnit field. A valid BusinessUnit value comes from another resource. This row-level BusinessUnitVVO1 LOV resource is always a sub-resource of an existing invoice resource, such as invoice 180428. 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.

  2. Use the REST-Framework-Version custom HTTP header in the client request to specify the framework version.

When a default framework version is not defined and no version header is passed, then the base version (version 1) of the ADF REST framework is assumed. To learn more, see:

HTTP Request Examples

Let's look at some examples of HTTP requests and payload structures of nested child resources, depending on the framework version that's used to process the request.

Example: REST Framework Version 1 and Version 2

In this example, you can retrieve the Opportunity resource, OptyId, and the specified items of the child resource, ChildRevenue, as an array of items, and not as a collection resource as in version 3.

cURL Command

curl --user <username:password> -H 'REST-Framework-Version:2' https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities?fields=OptyId;ChildRevenue:RevnAmount,ProdGroupName,StatusCode,Name1&onlyData=true

Example Response Body

{
  "items": [
    {
      "OptyId": 100000019836069,
      "ChildRevenue": [
        {
          "RevnAmount": 280,
          "ProdGroupName": "Support",
          "StatusCode": "OPEN",
          "Name1": "AMQA Accounts"
        },
        {
          "RevnAmount": 180,
          "ProdGroupName": "Support",
          "StatusCode": "OPEN",
          "Name1": "AMQA Accounts"
        }
      ]
    },
    {
      "OptyId": 300100017180741,
      "ChildRevenue": []
    },
   .
   .
   .
  ],
  "count": 25,
  "hasMore": true,
  "limit": 25,
  "offset": 0,
  "links": [
    {
      "rel": "self",
      "href": "servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities",
      "name": "opportunities",
      "kind": "collection"
    }
  ]
}

Example: REST Framework Version 3

In this example, you can retrieve the Opportunity resource, OptyId, and the specified items of the child resource, ChildRevenue, as a collection resource, and you then set the hasMore attribute to false, indicating that there are no more items to fetch.

cURL Command

curl --user <username:password> -H 'REST-Framework-Version:3' https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities?fields=OptyId;ChildRevenue:RevnAmount,ProdGroupName,StatusCode,Name1&onlyData=true

Example Response Body

{
  "items": [
    {
      "OptyId": 100000019836069,
      "ChildRevenue": {
        "items": [
          {
            "RevnAmount": 280,
            "ProdGroupName": "Support",
            "StatusCode": "OPEN",
            "Name1": "AMQA Accounts"
          },
          {
            "RevnAmount": 180,
            "ProdGroupName": "Support",
            "StatusCode": "OPEN",
            "Name1": "AMQA Accounts"
          }
        ],
        "count": 2,
        "hasMore": false,
        "limit": 25,
        "offset": 0,
        "links": [
          {
            "rel": "self",
            "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/100000019836069/child/ChildRevenue",
            "name": "ChildRevenue",
            "kind": "collection"
          }
        ]
      }
    },
    {
      "OptyId": 300100017180741,
      "ChildRevenue": {
        "items": [],
        "count": 0,
        "hasMore": false,
        "limit": 25,
        "offset": 0,
        "links": [
          {
            "rel": "self",
            "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/CDRM_461/child/ChildRevenue",
            "name": "ChildRevenue",
            "kind": "collection"
          }
        ]
      }
    }
  ],
  .
  .
  .
  "count": 25,
  "hasMore": true,
  "limit": 25,
  "offset": 0,
  "links": [
    {
      "rel": "self",
      "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities",
      "name": "opportunities",
      "kind": "collection"
    }
  ]
}

Example: REST Framework Version 4

In this example request to create employees in a department, the EmpName field causes a validation error. The response payload includes the HTTP status code and formats the details of the exception in an array structure.

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" http://server/demoapp/rest/1.0/Departments

Example Request Body

{
       "DeptNum" : 52,       
       "DeptName" : "newDept522",
       "Employees" : [
               {
                       "EmpNum" : 501,
                       "EmpName" : "MILLERSxxxxxxxxxxxxxxxxx"
               },
               {
                       "EmpNum" : 502,
                       "EmpName" : "SILLERSxxxxxxxxxxxxxxxxx"
               }
       ]
}

Example Response 

Content-Type : application/vnd.oracle.adf.error+json
REST-Framework-Version : 4
HTTP code: 400

Payload

{
  "title" : "Bad Request",
  "status" : "400",
  "o:errorDetails" : [ {
    "detail" : "Value MILLERSxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.",
    "o:errorCode" : "27040",
    "o:errorPath" : "/Employees/0/EmpName"
  }, {
    "detail" : "Value SILLERSxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.",
    "o:errorCode" : "27040",
    "o:errorPath" : "/Employees/1/EmpName"
  } ]
}

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