Oracle SaaS | Analysing the Structure and Morphology of the REST API Methods

Oracle SaaS API’s have a structure that is equal for all the “business entities” across the different modules (Finance, Loyalty, Supply Chain, …) such as invoices, expenses, loyalty transactions and so on. Let’s analyze the pattern. In this episode, we are focusing on the “Get all xxx” methods because it conforms a pattern that we’ll utilise in a sooner construct which we are working on for building a tool that extracts and publishes changes in the data in near-realtime.

Verb

Verb for all of them can be GET, POST,..

Endpoint

Endpoint is <fqdnurl>/<endpoint> where

<fqdn> is the server url such as https://iiii-eeee.fa.em2.oraclecloud.com
<endpoint> is the API endpoint provided in the documentation such as /fscmRestApi/resources/11.13.18.05/invoices 

Data Retrieved

If you execute the API call and data exists, conditions are valid and the user you are using for the connection has privileges to read, a JSON structure is retrieved up to the number of records in the limit parameter (default 25). If more records exist it is notified in the hasMore field in the response.

Parameters

expand: Includes child records of the entity, you can specify which childs to include or all for example ?expand=invoiceLines (tip: if onlyData is false (default) the links provide you the name of the child entities)
fields: If you don't want all the fields in the response, include the names of the fields expected
limit: maximum number of records per call execution
offset: the ordinal number of the set of records retrieved according to the total and the limit parameter. For example if limit is 5 and you want the records from 6 to 10, offset must be set to 1
onlyData: by default, response JSON includes child objects links, putting this value to false disables that option
orderBy: fields and order criteria for retrieving data such as ?orderBy=InvoiceId:asc,SupplierSite:desc
q: the filter condition to get data such as ?q=InvoiceAmount>1000
totalResults: by default is false so total records retrieved are not evaluated, if true they are counted with the drawback of a more computation cost and probably lower response time and performance

Example

In the following example we are requesting invoices and their lines with an amount greater than 1000 indicating that we want to know the number of invoices that accomplish the criteria

curl -X GET -k -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json' -u jxvxxr.mxgxxtx@xrxclx.cxm:password "https:/iiii-eee.fa.em2.oraclecloud.com//fscmRestApi/resources/11.13.18.05/invoices?limit=5&totalResults=true&q=InvoiceAmount>1000&expand=invoiceLines&onlyData=true"

Result

{
  "items" : [ {
    "InvoiceId" : 1,
    "InvoiceNumber" : "DFS03",
    "InvoiceCurrency" : "EUR",
    "PaymentCurrency" : "EUR",
    "InvoiceAmount" : 1100,
   …
    "CreationDate" : "2019-07-10T08:33:13+00:00",
    "CreatedBy" : "dxnx.fxrnxndxz@xrxclx.cxm",
    "LastUpdatedBy" : "dxnx.fxrnxndxz@xrxclx.cxm",
    "LastUpdateDate" : "2019-07-16T12:46:37+00:00",
    "LastUpdateLogin" : "8AC9D26BC392042BE053A46F660ACD78",
    "invoiceLines" : [ {
      "LineNumber" : 1,
      "LineAmount" : 1000,
      "AccountingDate" : "2019-07-10",
      …
      "MultiperiodAccountingAccrualAccount" : "",
      "CreatedBy" : "dxnx.fxrnxndxz@xrxclx.cxm",
      "CreationDate" : "2019-07-10T08:33:18+00:00",
      "LastUpdateDate" : "2019-07-10T08:34:56+00:00",
      "LastUpdatedBy" : "dxnx.fxrnxndxz@xrxclx.cxm",
      "LastUpdateLogin" : "8AC9F283AC3E043EE053A46F660A9D93"
    }, {
      "LineNumber" : 2,
      "LineAmount" : 100,
      "AccountingDate" : "2019-07-10",
      …
    } ]
  }, {
    "InvoiceId" : 1001,
    …,
    "invoiceLines" : [ {
      "LineNumber" : 1,
      "LineAmount" : 1000,
      …
    }, {
      "LineNumber" : 2,
      "LineAmount" : 100,
      …
    } ]
  }, …
    } ]
  } ],
  "totalResults" : 155,
  "count" : 5,
  "hasMore" : true,
  "limit" : 5,
  "offset" : 0,
  "links" : [ {
    …
}

So far, so good! Please note we have highlighted CreationDate and LastUpdateDate in the records, w’ll se the reason in a new post sooner, stay tuned!

So that’s all folks for now, hope it helps! 🙂

More Info

Oracle Cloud Applications Documentation Index

REST API for Finiancials

REST API for Supply Chain & Manufacturing