REST API for Oracle Public Sector Compliance and Regulation Cloud

Set the REST Framework Version

Oracle 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, declared using the restFrameworkVersion property in the adf-config.xml file. 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:

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.

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

Note that when your client doesn't include a version header in the request, the ADF REST framework uses the default version (version 1, 2, 3, or 4), as defined in the adf-config.xml file. 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 or 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"
  } ]
}

No matter which framework you use, each REST framework supports HTTP methods, HTTP headers, request URL parameters, media types, and other concepts to allow you to make REST API calls on resources.