Supported HTTP Methods

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

Note:

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

The following table lists the methods and their scope for singular and collection resources.

Method	Works with a Singular Resource?	Works with a Collection Resource?
GET	Yes. Gets a single resource.	Yes. Gets a subset, or all of the resources in the collection.
POST	No.	Yes. Creates a new resource in the collection.
PATCH	Yes. Updates a resource.	No.
DELETE	Yes. Deletes a resource.	No.

Supported HTTP Methods for SCIM Resources

The following table lists the methods and their scope for SCIM resources.

SCIM Resource	GET	POST	PUT	PATCH	DELETE	Filtering
Users	Yes	Yes	Yes	Yes	Yes	Yes
Roles	Yes	No	No	Yes	No	Yes
Bulk	No	Yes	Yes	Yes	Yes	Yes
Schemas	Yes	No	No	No	No	No
ResourceTypes	Yes	No	No	No	No	No

Supported HTTP Methods for BPM Resources

You can do the basic create, read, update, and delete operations on BPM resources using the GET, POST, PUT, and DELETE methods.

The GET Method

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

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

• expand
• fields
• onlyData
• limit
• offset
• q
• totalResults
• orderBy
• finder
• dependency
• links
• include
• includeChildren
• showAnnotations
• metadataMode
• resources
• partialDescription
• polymorphicType

expand

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

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

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

Example URL

/fscmRestApi/resources/<version>/invoices/359240?expand=invoiceLines

Example Response Body

{
    "InvoiceId": 359240,
    "InvoiceNumber": "Withholding tax - 300100170737078-2",
    "InvoiceCurrency": "THB",
    "PaymentCurrency": "THB",
    "InvoiceAmount": 5,
	. . .
    "invoiceLines": {
        "items": [
            {
                "LineNumber": 1,
                "LineAmount": 5,
                "AccountingDate": "2018-12-06",
                . . .
                "links": [
                    {
                        "rel": "self",
                    . . . 
    }
}

fields

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

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

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

onlyData

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

Example URL

/fscmRestApi/resources/<version>/announcements/300100090149733?onlyData=true

Example Response Body

{
"AnnouncementId": "300100090149733",
"CategoryCode": "OF",
"CreatedBy": "SEED_DATA_FROM_VERTICAL",
"CreationDate": "2017-05-18T08:51:04.001+00:00",
"ExpireDate": "2017-05-19T00:00:00+00:00",
"ExpiryDaysFlag": null,
"LastUpdateDate": "2017-05-18T08:51:07.609+00:00",
"LastUpdateLogin": "4FC58160B86257BCE0539D06F10A598C",
"LastUpdatedBy": "SEED_DATA_FROM_VERTICAL",
"ObjectVersionNumber": 1,
"StartDate": "2017-05-18T00:00:00+00:00",
"Subject": "meeting at 4pm ",
"Description": "meeting at 4pm",
   ...  
}

limit

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

offset

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

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

q

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

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

Supported operators in REST framework version 1:

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

The allowed special characters in REST framework version 1:

• \ (backslash) to define an escape character.
• * (asterisk) to define a wildcard character.
• " (double quotation mark) and ' (single quotation mark) to define a literal. You must add a space before and after the quoted string so that parameter values containing supported operators are interpreted correctly. Here's an example:

  Keyword=<SPACE>':204 WITHIN EGP_ITEM_ORG_SECTION AND :US WITHIN EGP_ITEM_LANG_SECTION AND AS54888'<SPACE> ;ItemDefinitionOrgId=204;OrganizationId=204;

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

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

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

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

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

totalResults

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

Example URL

/fscmRestApi/resources/version/announcements?totalResults=true&limit=5

Example Response Body

{
    "items": [],
    "totalResults": 55,
    "count": 5,
    "hasMore": true,
    "limit": 5,
    "offset": 0,
    "links": []
}

orderBy

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

finder

Uses the predefined where clause that includes certain bind parameters to search the collection. This parameter applies only to collection resources.

For example, the announcements resource defines a finder named PrimaryKey, with one of the bind parameters named AnnouncementId. A client can use this finder to fetch an announcement with a specific identifier.

For example:

finder=PrimaryKey;AnnouncementId=300100015957778

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

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

dependency

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

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

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

States?dependency=Country=BR

links

When the links query parameter is used to request a resource item or a resource collection, the response displays only those links with relation types (rel) that match the parameter values. The parameter value format is a comma-separated list (<rel_name>, <rel_name>) representing the relation type of a link. In the list, you can use any of the supported attribute values, such as self,canonical. This parameter applies to both singular and collection resources.

Note:

You can't combine the links parameter with onlyData when onlyData is set to true. That's because there will be no links section displayed in the payload.

include

Used to retrieve the description of resources of a certain visibility, as declared in the application. Visibility is set either to unlisted (for private resources) or public (for public resources). You can also retrieve resources of both types using all. The parameter value format is a comma-separated list (<visibility_type>, <visibility_type>) representing the visibility type of a resource. This parameter applies only to the describe request.

By default, only public resources appear in the describe response. To view private resources, you must append either ?include=all or ?include=unlisted to the describe request. You can combine this parameter with other parameters permitted for use with describe. For example,

/<resource>/describe?metadataMode=minimal&include=all

includeChildren

Used to either include or exclude all child resources nested within a parent resource. The response depends on the boolean value used for the includeChildren parameter:

• To include all child resources, append ?includeChildren=true to the describe request.
• To exclude all child resources, append ?includeChildren=false to the describe request.

You can combine this parameter with other parameters permitted for use with describe, except for /describe?metadataMode=list. This parameter applies to the describe and singular resources.

showAnnotations

You can use this parameter either to include or exclude annotations that are stored in a separate XML file associated with the resource. The response depends on the boolean value used for the showAnnotations parameter:

• To include the annotations, append ?showAnnotations=true to the describe request.
• To exclude or hide all child resources, append ?showAnnotations=false to the describe request.

You can combine this parameter with other parameters permitted for use with describe, except for /describe?metadataMode=list. Annotations, if defined, appear in the response by default, unless metadataMode=minimal. However, if you are using metadataMode=minimal and want to view the child resources, you have to append ?showAnnotations=true to the describe request. For example,

/<resource>/describe?metadataMode=minimal&?showAnnotations=true

metadataMode

You can use this parameter to determine the level of detail you retrieve from a describe request. By default, the full describe returns the complete set of information for all resources, including the metadata for each resource. To control the information retrieved, you can use the following parameter values:

• minimal: Append ?metadataMode=minimal to the describe request if you want to get only the titles and links of parent resources.
• list: Append ?metadataMode=list to the describe request if you want only the self links, without the metadata.

Optionally, you may append additional parameters to the metadataMode parameter. To include child resources, append includeChildren and to include resource annotations append showAnnotations. For example, you can append ?metadataMode=minimal&includeChildren=true to retrieve a minimal catalog describe with all children resources included in it.

resources

Used to filter and limit the resources returned in a describe response. The parameter value format is a comma-separated list (<resource_name1>, <resource_name2>) that contains the names of resources. You can combine this parameter with other parameters permitted for use with describe.

For example, if a catalog contains four resources: organizations, departments, employees, jobs, appending ?resources=employees,jobs to the request describe returns information only for employees and jobs.

partialDescription

You can use this parameter to control the metadata information that you can retrieve for resources in a parent-child nested hierarchy, in a resource collection. So, when you request metadata at the child resource, you can expect the response payload to contain the complete metadata for that child resource. However, for its children down the hierarchy, you can get links to their metadata, but not the metadata itself.

For example, the departments resource contains an employees resource, and the employees child resource contains another child called bonus. If your request is aimed at the employees child resource, you will get the metadata for employees but for the bonus child resource you will only get the link to its metadata. Here's a sample request based on the above example. Use the partialDescription parameter in the request:

/departments/describe?partialDescription=Employees

In the response body, examine the children element to get the partial describe link for the child resources in the hierarchy.

{
  "Resources" : {
    "Employees" : { 
      	
	  ...
     },

     "attributes" : [ {

      	  ...

       }]
          ...
	"children" : {
          "Bonus" : {
"$ref" :   "http://servername/restapi/resources/version/departments/describe?partialDescription=Employees.Bonus"
        },
      ...
      
	  "links" : 

      ...
      }
    }

}

You can use that link to view the metadata of the bonus resource.

Note:

You can't combine this parameter with any other parameter.

polymorphicType

You can use this parameter to retrieve the subtype information for a root resource that's polymorphic and has references to other items. Those items are accessible through individual links. To know whether a resource is polymorphic, you must first send a describe request at the resource level. If the resource is polymorphic, the response contains the polymorphic subtype information for the child or its children. For example, you send a describe request on the contacts resource:

https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/contacts/describe

The response may contain a link that you can use to view details of the polymorphic subtype. In this sample response, the link points to the polymorphic subtype contacts.addresses.addressesDFF.

},
              "subtypes" : {
                "discriminator" : "__FLEX_Context",
                "mapping" : {
                  "$ref" : "https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/contacts/describe?polymorphicType=contacts.addresses.addressesDFF"
                }

Click the link in the response and navigate further. Depending on the resource hierarchy, you will need to follow multiple links that appear in the response body. Continue navigating until you see the actual schema for that subtype along with its attributes and detailed metadata of the resource.

Note:

You can't combine this parameter with any other parameter.

The GET Method in v1 Resources

For v1 resources, to get details of a collection resource, you can use the request URL in this format:

GET /objects/<module_name>/v1/$openapi/<resource>

Get Object Details by a Resource Key

You can further narrow down the query for a resource using its resource key. A resource key is the concatenated string of the URL-encoded key values for the business object. The resource key can be a primary key, alternate key, or a composite key comprising multiple identifier fields. And all these values together form the resource identifier that's returned in the response payload.

To get the business object details by key, you can use the request URL in this format:

GET /objects/<module_name>/v1/$openapi/<resource>/<resource_key_value>

The resource identifier value appears in the $id field of the response payload.

Child Resources

For v1 resources, to get details of a child collection resource, you can use the request URL in this format:

GET /objects/<module_name>/v1/$openapi/<resource>/<resource_key_value>/<child_accessor_property_name>

The endpoint of a child resource collection is:

/<resource_name>/<resource_key_value>/<child_accesor_property_name>

The URI of a child resource is:

/<resource_name>/<resource_key_value>/<child_accessor_property_name>/<child_resource_key_value>

A resource can contain several child resources and the resource hierarchy can have multiple levels. For example:

• URL for a grandchild is

  /<resource_name>/<resource_key_value>/<child_accessor_property_name>/<child_resource_key_value>/<grandchild_accessor_property_name>

• URL for a great-grandchild is

  /<resource_name>/<resource_key_value>/<child_accessor_property_name>/<child_resource_key_value>/<grandchild_accessor_property_name>/<grandchild_resource_key_value>/<greatgrandchild_accessor_property_name>

Shaping

You can use the $fields parameter to choose the fields in a resource. To specify an absolute list of fields, you can use ?$fields=<field>,...,<field>.

Here, the field names of the same resource are separated by ','. You can specify the child and related resources using ".". For example:

?$fields=<accessor>.<field>".

A 400 Bad Request is returned if you include an unknown field in the request.

Default Shape

For v1 resources, unless values are specified on the URL, the parameters take their default values. For example, GET /<resource_name> would be:

GET /<resource_name>?$offset=0&$limit={defaultPageSize}

Business Views

A business view is a predefined view on a business object that simplifies querying across the business object hierarchy, in combination with the collection query parameters. If a business view has parameters, you can provide values for those parameters using URL parameters, to run the query. For parameters with default values, you don't have to pass any value.

For example: /orders/$views/exceptionOrders?paramDate=2020-12-01

In this example, the "exceptionOrders" view defines a filter condition "status = 'EXCEPTION' AND date > :paramDate" ("finds all orders in EXCEPTION state created after the specified date).

Query Over POST

For v1 resources, to get details of pagination, search, or sort criteria on the parent and child resources, you can use the POST method to query the resource:

Advanced Query

Advanced query is used to query a single resourse.

POST /.../orders/1/$query

Here's a sample request body:

{
	name: "getTimezoneList",
	description: "Gets multiple timezones", 
	request: {
	    path: "/objects/{$config.apiVersion}/timezones",
	    method: "GET"
}	}

Advanced Query all

Advanced query all is used to query a resource collection.

POST /.../orders/$query

Here's a sample request body:

Content-Type: application/json
	   {   
	     "collection": {     
		"filter": "date > '2020-12-01'"   
	     },
	     "fields": ["orderMode"],
	     "accessors": {
		"customer": {
	  	"fields": ["name"]
		},
		"lines": {
	  	"collection": {
		  "filter": "status = 'EXCEPTION'"
		},
		"accessors": {
  		"shipments": { 
		    "collection": { 
		      "sortBy": [{"shippedDate":"desc"}],
		      "limit": 1 
		    }  
	          }  
		  }  
		 }  
		}
	      }

The POST Method

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

application/vnd.oracle.adf.resourceitem+json

Note:

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

The POST Method in v1 Resources

To create a v1 resource, you can use the request URL in this format:

POST /invoices/v1/$openapi/invoices

Create a resource using POST on a collection URL with an appropriate json payload.

Example URL

POST https//<servername>/api/boss/data/objects/invoices/v1/$openapi/invoices/

{
    "invoiceId": "99",
    "invoiceNumber": "000099",
    "documentSequence": null,
    "total": {
        "currency": "USD",
        "amount": "2212.76"
    }
}

Example Response Body

Response
Status : 201
Cache-Control : no-cache, no-store, must-revalidate

You can create a child resource with a request URL in this format:

POST /invoices/v1/$openapi/invoices/000006/invoiceLines

The PATCH Method

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

application/vnd.oracle.adf.resourceitem+json

The UPDATE Method in v1 Resources

To update a v1 resource, you can use the request URL in this format:

PATCH /invoices/v1/$openapi/invoices/000002

Update a resource using PATCH on an item URL with an appropriate json payload.

Example URL

PATCH https://<servername>/api/boss/data/objects/invoices/v1/$openapi/invoices/000099

{
    "total": {
        "amount": "2212.77"
    }
}

Example Response Body

Response
Status : 204
Cache-Control : no-cache, no-store, must-revalidate

The DELETE Method

Use to delete a resource. The method doesn't require a request body.

The DELETE Method in v1 Resources

To delete a v1 resource, you can use the request URL in this format:

DELETE /invoices/v1/$openapi/invoices/000006

Delete a resource using DELETE on an item URL.

Example URL

DELETE https://<servername>/api/boss/data/objects/<module segments>/v1/$openapi/<resource>

Example Response Body

Response
Status : 204
Cache-Control : no-cache, no-store, must-revalidate

You can delete a child resource with a request URL in this format:

DELETE /invoices/v1/$openapi/invoices/000006/invoiceLines/000006,1

Custom Actions

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

The relevant request media type is:

application/vnd.oracle.adf.action+json

The response media type is:

application/vnd.oracle.adf.actionresult+json

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

application/vnd.oracle.adf.action+json

The JSON schema of the media type is:

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